Troubleshooting
First stop: https://<your lodesong>/api/health. It says, per configured server, whether lodesong reaches it, how fast, and what it is.
Can't reach Navidrome
The sign-in screen says can't reach navidrome, /api/health shows "reachable": false.
NAVIDROME_URLis what the container uses.localhostinside a container is the container itself; use the Navidrome service name (http://navidrome:4533) and put both on one Docker network (networks:in both composes, or one compose with both services).- Test from inside:
docker compose exec player wget -qO- "$NAVIDROME_URL/rest/ping"should print JSON.
"The server answered, but it isn't Navidrome"
NAVIDROME_URL points at something else: often a reverse proxy's web page, or the wrong port. It must be the base
URL that has /rest/ping under it.
"Wrong username or password" with the right password
- The account is the Navidrome account (case-sensitive user name).
- After 3 wrong tries each further one waits longer (1 s, 2 s, 4 s … up to 15 min), per IP and per user; the message says how long.
- Behind a reverse proxy, set
TRUST_PROXY=true, or every user shares the proxy's IP for rate limits.
Pasted links don't unfurl, or the preview image is missing
- A crawler only sees the details of an item when the link came from "copy share link" (item menu); a plain address shows the generic card. Copy the link again if it was stopped or is older than 180 days.
- The image address comes from
PUBLIC_URL, or from the request when that is unset. Behind a reverse proxy setPUBLIC_URL, orTRUST_PROXY=truewith the proxy passingHostorX-Forwarded-HostandX-Forwarded-Proto. - Titles in scripts the bundled fonts lack (CJK, Arabic, Hebrew, Thai) can't be drawn on the card: it uses the artist (or the first part of the subtitle it can draw) as the headline, or just the kind if nothing is drawable. The preview text above the card keeps the real name.
- Chat apps cache previews; a changed card can take a while to show.
Songs start slowly or skip
- Look at the browser's network panel: each
/rest/streamresponse hasServer-Timing: upstream;dur=…, the time Navidrome took to answer. Seconds there mean Navidrome itself is slow (a full scan running, a busy disk). - Large FLACs over a slow link: the next songs only download after the current one is buffered, but a very slow
connection can still stall. The player waits as long as bytes keep arriving and only gives up on a stream that
is silent for 8 s, four times.
Set stream quality to a transcode (auto already streams most songs as Opus 192), and
check the server's link: a port negotiated at 10 Mb/s (
ethtool <nic> | grep Speed) is about 1 MB/s, which a bad cable or router port causes. - "it's in a format this browser can't play": the browser has no decoder for the file type (e.g. ALAC in Firefox). lodesong retries the song as an MP3 320 transcode on its own; Navidrome does the converting.
Streams cut off behind a proxy
Disable response buffering and allow long responses (nginx: proxy_buffering off; proxy_read_timeout 1h;). See
deploy.
Search misses songs or lyrics
User menu → library index (admins): counts, last sync, "rebuild now". The index syncs after Navidrome scans; a song added a minute ago appears after the next scan. Lyrics are searchable once fetched; the backfill takes about a second per song.
Bad configuration
The server refuses to start and lists every bad variable:
lodesong: can't start, fix the configuration (see docs/configuration.md):
- PORT must be a whole number from 1 to 65535, got "eighty"Reset a browser
User menu → offline storage → clear, then log out. That removes this account's cached music, covers and queue from the browser.