Troubleshooting

The most common problems and what you can do about them. If nothing works, send a report from Tune: it contains everything needed for a diagnosis.

The interface does not open

Check that Tune is running: the console window on Windows, sudo systemctl status tune-server with the .deb package, sudo systemctl status tune on Tune OS.
The address is http://<server-address>:8888; on Tune OS, http://tune-XXXX.local or http://<IP-address>.
Freshly installed Tune OS: the first boot takes 15 to 30 minutes, with two automatic reboots. A machine that already answers over SSH is not necessarily done. Progress is written to /var/log/tune-os-firstboot.log.
Windows, no access from another device: Windows Firewall blocks Tune on the "Private network" profile. Allow tune-server.exe on private networks in Windows Firewall. The same block also prevents DLNA discovery.
Port already in use: pick another port with TUNE_PORT (see Configuration). On Windows, since 1.0.0-rc2, launching Tune from its shortcut while it is already running simply opens the running instance in the browser.
Docker: the container restarts in a loop (on a NAS, it stops unexpectedly): the folder mounted on /data is not writable by the tune user (uid 1000). That is the case for a folder Docker created by itself, such as ./data. Replace it with the named volume tune-data:/data (see Getting Started), or give that folder to uid 1000: sudo chown -R 1000:1000 ./data. Then run docker compose up -d again.

A device does not show up

The device and the server must be on the same network (same subnet, same VLAN). Discovery uses multicast: SSDP (UDP 1900) and mDNS (UDP 5353).
With Docker, use network_mode: host.
Look in Settings › Audio › Ignored devices: the device may have been hidden.
If the machine has several network cards (or a VPN), tell Tune which address to announce with TUNE_ADVERTISED_IP.
An LMS on the same machine holds port 3483, so Squeezebox players will not see Tune.

No sound

Local output

Check the Audio backend in Settings › Audio › Local Audio Outputs. On Windows, ASIO needs the DAC maker's driver.
Another application may be holding the DAC in exclusive mode: close it.
Linux (.deb package): the service runs as the tune user, which must belong to the audio group.
Linux: in 1.0.0-rc1, a stuck ALSA/PipeWire scan could freeze Tune, which then had to be restarted by hand. Since 1.0.0-rc2, such a stall no longer freezes the server. If the audio output still drops, send a report from Tune.
Single-processor machine: since 1.0.0-rc2, Tune always keeps at least 4 worker threads, to avoid the freezes of several seconds that interrupted local playback.

Network device

Settings › Audio › Audio diagnostic (Expert level) and the Signal Path in the playback bar show what is sent to the device.
Check that the device accepts the format being sent. For DSD, try Auto or PCM (conversion) in Settings › Devices › Per-zone settings.
Dropouts in DSD 256/512 to a renderer: Settings › Audio › DSD playback (network renderers), option Continuous streaming. After updating to 1.0, check that this option is still the one you chose.

Windows: ASIO falls back to WASAPI at startup

Symptom: ASIO is selected, but when Tune starts only WASAPI outputs (e.g. "Speakers") appear, or playback stalls. 1.0.0-rc2 fixes the two known causes of this fallback: Tune now waits for the ASIO driver scan to finish before falling back to WASAPI. If it falls back anyway, it switches back to ASIO by itself at the next device scan, as soon as nothing is playing on a local output.

Check that Settings › Audio › Local Audio Outputs › Audio backend is set to ASIO and that the maker's ASIO driver is installed.
Restart Tune.
If Tune shows ASIO scan paused after a crash, it has turned off the ASIO driver scan to avoid a crash loop. Click Re-arm the ASIO scan, then restart Tune.
If the problem persists, send a report from Tune and mention your DAC and its driver.

Tune OS: covers and artist photos gone in 1.0.0-rc1

In 1.0.0-rc1, Tune OS looked for the cover cache in /opt/tune/data/artwork_cache, while earlier versions had stored it in /opt/tune/artwork_cache: nearly all covers and artist photos seemed lost. 1.0.0-rc2 fixes this. At startup, Tune goes back to the original cache and copies into it what rc1 had stored elsewhere, without overwriting or deleting anything. So all you need to do is update Tune. If you had already copied the images by hand, there is nothing to undo.

Library

An added folder does not appear: the path must exist on the machine running Tune and be readable by the account Tune runs as. After the first start, changing TUNE_MUSIC_DIRS has no effect: use Settings › Library › Locations.
Changes on a network share are not seen: Tune checks a share every 15 minutes. To speed things up, run Scan the library again.
The ReplayGain gauge went back to 0 % after an update or a restart in 1.0.0-rc1. Since 1.0.0-rc2, it counts the tracks already analysed across the whole library.
Network share not ready at startup: since 1.0.0-rc2, for an SMB share it mounts itself, Tune waits for the first mount attempt before scanning the library, then keeps retrying in the background for about 5 minutes. Covers are no longer removed while the share is missing.
A cover changed after the update: since 1.0.0-rc2, the folder image (e.g. cover.jpg or folder.jpg) takes precedence over the cover embedded in the files. For a box set stored one folder per disc, the image at the root of the box set wins. A cover you uploaded is never replaced.
Background analyses use too much of the machine: lower Settings › Audio › Background analysis speed, or pause them from Server status.

Streaming services

Deezer: "ARL rejected by Deezer" or a lost session: open deezer.com, get a new arl cookie and paste it into Settings › Access and tokens › Streaming Services.
TIDAL, Qobuz: disconnect and reconnect the service in the same place.
YouTube: without Enable YouTube playback, search works but playback fails.
Spotify: in 1.0 the catalogue can be browsed but not played. To connect the account, you need the Client ID of your own Spotify app (see Streaming Services).
Bandcamp: a track started again several days later from the queue, the history or a favourite may no longer play, because its address has expired. Since 1.0.0-rc2, the failure is written to the log, and a Chromecast zone stops and reports the error instead of staying silent. Start the track again from its album page.

Sending a report from Tune

Open Support at the bottom of the sidebar.

Report a bug (Diagnostics tab)

Open to everyone, no licence needed. Describe What happens, add screenshots if useful, then click Send to the forum. Your text, the diagnostics and the server's recent logs go to a moderated forum thread. Personal paths are removed from the report, and View the attached report shows it to you before sending.

If Tune answers with a sending limit message, sometimes even on the very first try (a known issue, reported), use Copy the report and paste it into a new topic on the forum, or try again later.

Write to support (Tickets tab)

This form shows when a Tune Premium licence is registered. It has Subject, Category, Zone concerned (optional), Your message and Attachments (up to 5 files). Leave Attach the logs and the system report ticked: without them, a diagnosis often takes several rounds. Follow up on your requests in the Tickets tab.

Logs

Settings › System › Server Health (Advanced level): Download logs, or Download diagnostics (a ZIP with logs, diagnostics and configuration, credentials masked). The Log level is set in the same place.
Files: see the "Where data lives" table in Configuration.