Troubleshooting
The most common problems and how to fix them. If yours isn’t listed, open an issue on GitHub and attach the log file.
Up to date for version 0.4.3
Documentation
Installation
| Problem | Fix |
|---|---|
| “Windows protected your PC” | Click “More info”, then “Run anyway”. The installer isn’t commercially signed. |
| macOS won’t open the app | System Settings → Privacy & Security → “Open Anyway”. |
| “RustMusic is damaged” | In Terminal: xattr -cr /Applications/RustMusic.app |
| “GLIBC_2.39 not found” | Install the glibc 2.35 compatibility build (Downloads page). |
| AppImage won’t start | Make it executable (chmod +x) and install libfuse2. |
| The interface flickers while scrolling (Linux) | Leave DMA-BUF on “Auto” in Settings → Appearance → Expert options, or turn it off, then click “Restart now”. |
| The interface is slow (modest or virtual machine) | Choose “Light” in Settings → Appearance → Expert options → Visual effects. The change is immediate. |
Sound
- No sound in exclusive mode: another app may already be using the output. Close it, or switch back to shared mode in Settings → Audio.
- The DAC always shows the same sample rate: check that exclusive mode is on and that the right output is selected.
- Other apps have no sound: that’s the normal effect of exclusive mode on that output; they come back when playback stops.
- The badge does not say “Bit-perfect”: check for a lossless source, a DAC that supports the sample rate and channels, volume at 100% and ReplayGain off or neutral. The “Exclusive” badge only indicates a reserved output.
- Linux, “No direct access to this output” with a USB DAC: update RustMusic. Since 0.2.10, it finds the card behind the PipeWire output even when PipeWire and ALSA name it differently.
- A track skips or jumps back during playback (files on a network drive): fixed in 0.2.10, the transition now waits until the track is fully decoded.
- At launch, resuming played a few seconds of silence before starting: fixed in 0.3.0, the track now picks up straight at the saved position.
- Changing the output or mode only applied to the next track started: since 0.3.1, it takes effect immediately, without restarting the app.
- Linux, exclusive mode: the DAC disappeared from the output list, which only showed “Dummy Output”. Fixed in 0.3.1: it stays there, selected.
- Linux, no sound with PipeWire alone (the Flatpak package in particular): fixed in 0.3.1, RustMusic connects to the sound server in every case.
DSD
- The DAC shows a PCM rate instead of “DSD”: turn on “Native DSD (DoP)” and exclusive mode, and check that your DAC supports DoP.
- Noise instead of music: the DoP stream was altered on the way. Check that no other software applies an equalizer or effect to the output.
- A gap between DSD tracks: update RustMusic, then check gapless playback in Settings → General. Since 0.2.8, DoP can play gaplessly on all three systems; a format change may require reopening the output. Version 0.2.9 also fixes queues getting stuck with DSD converted to PCM.
Library
- New files don’t show up: click “Rescan”. RustMusic doesn’t watch folders continuously.
- A folder is marked “Unavailable”: the network share isn’t mounted or the drive is unplugged. Its tracks are kept; plug it back in, then rescan.
- The NAS was mounted again under another name (by its address, then by its name, or the other way round): RustMusic recognizes the same share and offers to update the library; tracks, playlists, favorites and queue follow.
- A compilation only has its first track: before 0.2.10, a compilation without an “album artist” tag could lose its other tracks on import. Update, then run a new scan.
- No cover: “Fetch covers” in the library’s “Manage” menu.
- No lyrics: put a .lrc file with the same name next to the track, or wait until they are available on LRCLIB.
- A guest artist is missing: Settings → Storage → “Artist links” → “Repair”.
- Two artists show up as one (“Chris Brown/Nicki Minaj”): Settings → Storage & data → “Check multiple artists”. A band was split by mistake: “Review corrections”, then “Undo”.
- A composer is missing from the Composers view: their name isn’t in the composer tag; fill it in in the tag workshop.
Radio, podcasts and servers
| Problem | Fix |
|---|---|
| No Radio or Podcasts page | Turn them on in Settings → Online listening: they are off by default. |
| A station sounds muffled | Its stream is AAC+ (“AAC+” badge): the decoder only plays it at reduced quality. If the station offers another one, pick it under “Stream quality” in the “…” menu. |
| “The station stopped responding” | The station cut its stream, or the network was down for too long. RustMusic reconnects on its own after a short dropout; otherwise, start the station again. |
| “Preview unavailable” | The show’s feed isn’t responding for now. Try again later, or add the show by its RSS feed address. |
| A show has no feed | Some shows don’t publish a public RSS feed: RustMusic can’t follow them. |
| A server is “Unreachable” | Check that it is on and that the address is correct in Settings → Storage & data. Its tracks kept offline stay playable. |
| The DLNA server isn’t found | A server in Docker or on another network doesn’t announce itself: add it by its address, for example http://127.0.0.1:8200. |
Network: players, AirPlay and DLNA
| Problem | Fix |
|---|---|
| No network player in “Audio output” | Turn on “Play on a network player” or “Play on an AirPlay device (v1)” in Settings → Network & DLNA: these features are off by default. Then check that the device is on and on the same local network (not the guest Wi-Fi), and click “Search”. |
| Devices not found with a VPN on | Update RustMusic: since 0.3.0, the search starts from every network adapter and the DLNA server no longer announces itself inside the tunnel. If a device is still missing, check that your VPN lets local network traffic through. |
| An AirPlay device doesn’t show up | It is probably password-protected, or only accepts AirPlay 2: RustMusic only handles AirPlay 1, without a password. |
| A short gap between tracks on Sonos | That is expected: Sonos speakers leave a short gap between tracks. On other players, playback stays gapless. |
| A DSD file refused by the network player | The device says it can’t play this format, and RustMusic flags it instead of sending the file. Play it on one of the computer’s outputs (native DSD or converted to PCM). AirPlay doesn’t support DSD yet. |
| macOS 15: no device found, DLNA server invisible | Allow RustMusic in System Settings → Privacy & Security → Local Network. Without that permission, macOS silently blocks the search and the server. |
| The device can’t see the RustMusic server | “Share on the network” turned on, same local network, firewall allowed and app open. Some routers filter multicast between Wi-Fi and Ethernet: check client isolation in your router settings. |
| The amplifier refuses pause or seeking on the DLNA server | Fixed in 0.3.0: the server now says it accepts them. Update RustMusic. |
| The amplifier stops after the first track of an album served by RustMusic | Fixed in 0.3.1: the DLNA server describes each track and the real number of tracks in an album or folder. Update RustMusic. |
| A file won’t play on the device | The device may not support its format or sample rate. |
Amplifier remote
- “No amplifier found”: the remote controls Onkyo, Pioneer, Integra, Denon, Marantz and Yamaha amplifiers. Check that the amplifier is on or in network standby and on the same network as the computer, then click “Search” in Settings → Remote. On macOS 15, local network access permission is needed too.
- The amplifier is “unreachable”: RustMusic retries every 5 seconds and picks it up again on its own as soon as it responds, even if its address on the network has changed.
- The amplifier doesn’t switch off on a click: that is by design. Hold the power button for a little under a second, until it fills with red.
Log and reset
RustMusic writes a log in the logs subfolder of its data folder (rustmusic.log). Since 0.2.9, it also records the selected output, audio chain and conversions, alongside errors. Attach it to your issues. “Data folder” in Settings → Storage opens the folder.
As a last resort, “Reset application” starts again from a clean state. Export your settings and playlists first.
Further reading
Question not answered?
Open an issue on GitHub: every report helps improve RustMusic and this documentation.