Troubleshooting

Here are the most common pitfalls and what's really behind each of them.

Sign-in

Sign-in fails even though the password is right

It's almost always a cookie problem, because the HTTPS setting doesn't fit.

Out of the box, Tunetorch assumes it's running behind a TLS reverse proxy and sets its sign-in cookies with the Secure flag. If you open it directly over HTTP, the browser discards these cookies. The sign-in seems to fail, even though the server accepted it.

    environment:
      TT_HTTPS: "False"
      TT_TRUSTED_PROXIES: "0"

After that you have to recreate the container. A simple restart doesn't pick up changed environment variables:

docker compose up -d

To check, look at the server log (docker logs tunetorch). If the setting is wrong, right after the sign-in attempt there's the line [TT-AUTH-007] TT_HTTPS=True, but the login request came in over HTTP. With a wrong password, it would instead say [TT-AUTH-009] Login failed: invalid credentials. In a German log the text after the code is German, the code is the same.

Why it still worked during setup: over http://localhost:5000, Chrome, Edge and Firefox accept Secure cookies anyway, because they treat localhost as secure. The first sign-in and the password change directly on the server therefore work even with the wrong setting. Only access from a second device via the LAN address fails. Then it's easy to suspect the new password, even though it has nothing to do with it.

I keep getting signed out after about 15 minutes

The access token expires after 15 minutes and is normally renewed without you noticing. If the renewal doesn't work, you see exactly this pattern.

There are two possible reasons:

  1. The sign-in key was regenerated, for example because the data directory was reset or forgotten during a move. All old sign-ins are then invalid.
  2. Old cookies from an earlier version are still in the browser.

In both cases this helps: delete the site's cookies and sign in again. To stop it happening again, jwt/ belongs in the backup; see Security & backup.

I'm locked out (“too many failed attempts”)

The brute-force protection has blocked your IP (default: 10 failed attempts within 10 minutes lead to a 60-minute block). Wait for the block to end or change the values in the server settings.

Is everyone locked out at the same time? Then the server only sees your reverse proxy's IP. Set TT_TRUSTED_PROXIES to the number of proxies in front (usually 1).

Nobody can get into the administration any more

If the password of the only admin account is gone, reset it on the server, directly in the running container:

docker exec -it tunetorch tt admin-reset <username>

What the command does, what it doesn't do and why it isn't a security hole is described under Resetting the admin password.

Container & start-up

The container doesn't start, and the log reports “[entrypoint] FEHLER”

Tunetorch can't write to /app/data (FEHLER is German for “error”). On start-up, the container tries to hand the directory over to the configured UID:GID. If that doesn't work (read-only file system, ACLs), it aborts instead of only half working later on.

Check the owners on the host:

ls -ln ./tunetorch-daten

and set TT_PUID/TT_PGID to match. On Synology DSM that's often 1026:100. If there's also an ACL, explicitly give the user with this UID write permission in File Station.

The container is running, but the page doesn't load

docker ps                       # status healthy/unhealthy?
docker compose logs -f tunetorch

If docker ps shows the container as unhealthy, the server is no longer responding. A restart helps, and you'll find the reason in the log. If it says healthy, it's more likely down to the port forwarding or the reverse proxy.

Something is missing after an update

Tunetorch applies changes to the database itself on start-up. Check the log to see whether that worked. Also check in the server status which version is really running. A docker compose up -d without a pull beforehand may start the old image again.

The server no longer starts after an update

If the log says a schema migration failed, the database may only be half converted. Then it doesn't help to simply use the old image, because it doesn't know the new structure.

Tunetorch made a copy before the change:

docker exec -it tunetorch tt db-sicherungen
docker exec -u root -it tunetorch tt db-einspielen auto-schema23-20260819-1930.db

After that, enter the previous version in the docker-compose.yml and restart. Otherwise the new server immediately tries the same change again.

The copy is kept for as long as the change keeps failing. Tunetorch only clears away old backups once an update has gone through completely. So you don't have to act in a hurry, even if the container keeps running and trying again and again.

Details under Security & backup.

Library

The library is empty after the scan

An album appears twice in the library

The classic: the artist is tagged in two spellings (“Voxxclub” and “voXXclub”), and so two albums are created.

The metadata assistant finds exactly that under Spelling duplicates, and merging makes the duplicate disappear at the same time. It belongs to Pro. Without a subscription, correct the spelling in the metadata editor; the merge happens just the same. Uploading, importing and scanning no longer create new duplicates: if the name already exists in exactly one other spelling, Tunetorch uses that one.

A combined artist has a card of its own, almost empty

“Beth Hart & Joe Bonamassa” was created as an artist of its own. Split it up as a collaboration album in the metadata editor. The album is then attached to both real artists, and the superfluous card disappears.

An album is listed under “Collaboration albums” although it isn't one

That happens when the second name is in the artist line on all tracks of the record. Then the album counts as a joint one. But you only wanted to enter a guest on individual tracks?

Then enter them only there: in the metadata editor via the Contr. column of the track row in question, not via Maintain for the whole album…, because that writes to every track. You can remove a name that's already entered album-wide there again. Whether the guest is in the artist line or appears as an addition after it makes no difference to how the album is filed.

Cover art is missing

Changes don't show up

The library is cached on the device. Tunetorch checks for changes at startup if the cached copy is more than an hour old, and whenever you return to the app (at most every five minutes). If you want the new state right away: User settings → Advanced → Library → Sync library.

The log says “database is locked”

A long write (scan, import, export) briefly blocked the database. Tunetorch pauses between its writes and waits up to 60 seconds for the database to be free again. Individual messages are therefore harmless. If they pile up, run large jobs at night.

Playback

Crackling or dropouts over Bluetooth

Increase the buffer size under User settings → Playback → Audio processing (Automatic → 0.3 s → 0.5 s → 0.75 s). With a larger buffer the equaliser reacts a little more slowly, but most dropouts over Bluetooth disappear.

A track breaks off on a poor connection

That shouldn't happen, because Tunetorch loads every track in full before it starts. If it happens anyway, check in the debug log whether loading broke off. A lower quality level reduces the amount of data.

Playback stops when the screen turns off (Android)

In the PWA this is due to the system's power-saving mode. There are two ways around it:

  1. Use the Android app. It plays independently of the browser and isn't affected.
  2. Give the browser (not the PWA) a battery exception.

A track has no loudness matching

It's missing its measured value. Either the measurement failed for this file during upload or import, or the track comes from a folder mounted read-only, where nothing is measured when reading in. Usually both sort themselves out: the next time it plays, Tunetorch measures it and remembers the result. The track change then takes a little longer, once. That applies in the app and the browser just as when casting.

If you don't want to wait until every affected track has had its turn once, let the Measure loudness maintenance task run. It measures all tracks without a value at once, uploaded and mounted alike. It's off out of the box, because it runs a full audio analysis for every file and loads the server accordingly.

App & car

“App not installed” (installing from an APK file)

That's Play Protect, which blocks installations from outside the store. Confirm the notice (“Install anyway”) or briefly switch Play Protect off. This doesn't happen when installing from the Play Store.

A second possible reason: the test and store versions are signed differently and can't be installed over each other. In that case uninstall the old one first.

Where do I find the installation instructions?

Under Settings → “App” tab → Installation. It shows exactly the way that fits your device (Android: Play Store, iOS and computer: web app). In the Android app the section is missing; the app version is shown there instead.

Android Auto doesn't show Tunetorch

If the app was installed from an APK file (on test devices, for example), Android Auto only shows it if “Unknown sources” is enabled in the developer settings. With an installation from the Play Store that isn't necessary.

All lists in the car are empty

Then the app couldn't load the library, usually because there was no reception at start-up (underground car park, dead zone). In that case an entry with the name of the list and “Couldn't be loaded · Tap to try again” appears at the top of the tab. Tapping it tries again, and as soon as the phone has reception again, the app loads by itself. An expired sign-in is renewed by the app itself with the saved password. If it stays empty, check whether the server can be reached.

If it says “Sign-in needed”, the server rejected the saved password, for example because you changed it. Open the app on the phone: it goes straight to editing the connection. Enter the new password there. Only then can the app sign in by itself in the car again.

A list in the car stops in the middle of the alphabet

Android Auto only shows lists up to a certain length. That's why Tunetorch splits long lists up itself: from 200 entries on, there's first a choice by initial letter (A · B · C … · #). If a letter is itself too full, a choice by the second letter follows (Sa · Sb · Sc …). Playlists and “recently played” lists are split into sections (“1–200” …). If you don't see this grouping, your app is too old. Update it.

Tabs or menu items are missing in the app

Only in the Android app does the App tab show the storage areas (audio cache, downloads, cover cache). In the browser it shows the installation instructions instead. And in offline mode, all features that need the server are hidden (upload, statistics, playlists, editing, export). You can tell by the offline icon next to the username.

Casting

I don't see a device selection in the user menu

Three things have to be in place for that:

  1. The main switch under Server settings → DLNA is on.
  2. Your account has the DLNA permission.
  3. At least one device is entered and reachable.

The device isn't found when adding it

Playback doesn't start even though the device is there

Usually the Server address for the playback devices is missing. It has to contain your server's address on the home network including the port (http://192.168.1.50:5000), not localhost, not the container's IP and not your public domain. The speaker fetches the music itself via this address.

The device doesn't show the artist and album

Tunetorch sends all the details, but whether a device displays them is up to its firmware. Closed systems often only show the title and cover art when controlled from outside. Unfortunately there's nothing we can do about that.

Ripping CDs

The “Rip CDs” menu entry is missing

It only appears when there is something to do: CD ripping is switched on in the server settings, your account has the Rip audio CDs permission (or is an admin), and there is an audio CD in a drive enabled for ripping — or you have read CDs still waiting to be transferred. A data CD or an empty drive doesn't count. If the drive only shows up under Detected drives in the server settings, it hasn't been enabled yet. A CD you've just inserted appears the next time you open the menu. If the server doesn't see any drive at all, the /dev:/dev line in the Compose file is usually missing (Passing through a CD drive). On a Synology NAS, the driver for the drive is usually missing instead (Synology NAS (DSM)).

“No access to the drive”

The server sees the drive but isn't allowed to open it. The number under group_add is almost always wrong. It has to be the group that owns /dev/sr0 on the host (stat -c '%g' /dev/sr0). After the change, recreate the container (docker compose up -d).

Tracks stay “consistent” but never become “verified”

Either AccurateRip doesn't know the CD (which is normal for rare pressings), or the drive's read offset is missing or wrong. Let it be detected automatically in the server settings with a widely available CD. If the detection reports “several pressings”, insert a different CD and start it again.

The rip keeps breaking off, and the drive disappears

On a Raspberry Pi that's almost always down to the power supply. When spinning up, the drive needs more power than the USB ports deliver. A drive with its own power supply or a powered USB hub fixes it. Tracks already read aren't lost. With the same CD, Resume reads only the missing ones.

If the Pi boots from a USB SSD, the whole Pi can hang instead of just the drive. It then still answers pings, but no longer responds to SSH. Connect the drive to a powered hub and keep the SSD directly on the Pi (Passing through a CD drive).

Finding logs

The built-in log viewer (Server settings → Logs) shows the last hour up to 28 days, filterable by source and level. From outside, this is how you get at the logs:

docker compose logs -f tunetorch

If you need more detail, temporarily set TT_LOG_LEVEL to DEBUG.

Every line starts with a code such as [TT-DLNA-012]. It is the same in both log languages (Server settings → Server log language), and it lets anyone look the line up.

None of this helps?

Write to us via the contact form (topic Bug report) or come to the Discord server. It has a support forum where you file your question by platform (Docker, NAS, Raspberry Pi, Android, web player, DLNA). Write in English or German — we answer in both. These help:

Back to the documentation overview