Fehlerbehebung

Hier stehen die häufigsten Stolpersteine und was jeweils wirklich dahintersteckt.

Anmeldung

Die Anmeldung schlägt fehl, obwohl das Passwort stimmt

Fast immer ist das ein Cookie-Problem, weil die HTTPS-Einstellung nicht passt.

Tunetorch geht ab Werk davon aus, dass es hinter einem TLS-Reverse-Proxy läuft, und setzt seine Anmelde-Cookies mit dem Secure-Flag. Rufst du es direkt per HTTP auf, verwirft der Browser diese Cookies. Die Anmeldung scheint fehlzuschlagen, obwohl der Server sie angenommen hat.

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

Danach musst du den Container neu erstellen. Ein einfacher Neustart übernimmt geänderte Umgebungsvariablen nicht:

docker compose up -d

Zur Kontrolle schaust du ins Server-Log (docker logs tunetorch). Ist die Einstellung falsch, steht direkt nach dem Anmeldeversuch die Zeile [TT-AUTH-007] TT_HTTPS=True, aber der Login-Request kam über HTTP. Bei einem falschen Passwort stünde dort stattdessen [TT-AUTH-009] Login fehlgeschlagen: Ungültige Anmeldedaten.

Warum es beim Einrichten noch ging: Über http://localhost:5000 akzeptieren Chrome, Edge und Firefox Secure-Cookies trotzdem, weil localhost für sie als sicher gilt. Erster Login und Passwortwechsel direkt auf dem Server klappen deshalb auch mit falscher Einstellung. Erst der Zugriff von einem zweiten Gerät über die LAN-Adresse scheitert. Dann hat man schnell das neue Passwort im Verdacht, obwohl es daran gar nicht liegt.

Ich werde nach etwa 15 Minuten immer wieder abgemeldet

Der Access-Token läuft nach 15 Minuten ab und wird normalerweise unbemerkt erneuert. Klappt die Erneuerung nicht, siehst du genau dieses Muster.

Dafür gibt es zwei mögliche Gründe:

  1. Der Anmelde-Schlüssel wurde neu erzeugt, etwa weil das Datenverzeichnis zurückgesetzt oder beim Umzug vergessen wurde. Alle alten Anmeldungen sind damit ungültig.
  2. Alte Cookies aus einer früheren Version liegen noch im Browser.

In beiden Fällen hilft: Cookies der Seite löschen und neu anmelden. Damit es nicht wieder passiert, gehört jwt/ mit ins Backup, siehe Sicherheit & Datensicherung.

Ich bin ausgesperrt („zu viele Fehlversuche“)

Der Brute-Force-Schutz hat deine IP gesperrt (Standard: 10 Fehlversuche in 10 Minuten führen zu 60 Minuten Sperre). Warte die Sperre ab oder ändere die Werte in den Server-Einstellungen.

Sind alle gleichzeitig ausgesperrt? Dann sieht der Server nur die IP deines Reverse-Proxys. Setze TT_TRUSTED_PROXIES auf die Zahl der Proxies davor (meistens 1).

Niemand kommt mehr in die Verwaltung

Ist das Passwort des einzigen Admin-Kontos weg, setzt du es auf dem Server zurück, direkt im laufenden Container:

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

Was der Befehl tut, was er nicht tut und warum er keine Sicherheitslücke ist, steht unter Admin-Passwort zurücksetzen.

Container & Start

Der Container startet nicht, das Log meldet „[entrypoint] FEHLER“

Tunetorch kann nicht in /app/data schreiben. Beim Start versucht der Container, das Verzeichnis an die eingestellte UID:GID zu übergeben. Klappt das nicht (schreibgeschütztes Dateisystem, ACLs), bricht er ab, statt später nur halb zu funktionieren.

Prüfe die Eigentümer auf dem Host:

ls -ln ./tunetorch-daten

und setze TT_PUID/TT_PGID passend. Auf Synology DSM ist das oft 1026:100. Kommt eine ACL dazu, gib dem Benutzer mit dieser UID in der File Station ausdrücklich Schreibrecht.

Der Container läuft, aber die Seite lädt nicht

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

Zeigt docker ps den Container als unhealthy, antwortet der Server nicht mehr. Ein Neustart hilft, und den Grund findest du im Log. Steht dort healthy, liegt es eher an der Portweiterleitung oder am Reverse-Proxy.

Nach einem Update fehlt etwas

Änderungen an der Datenbank spielt Tunetorch beim Start selbst ein. Schau ins Log, ob das geklappt hat. Prüfe außerdem im Server-Status, welche Version wirklich läuft. Ein docker compose up -d ohne vorheriges pull startet unter Umständen wieder das alte Image.

Nach einem Update startet der Server nicht mehr

Steht im Log, dass eine Schema-Migration gescheitert ist, ist die Datenbank womöglich nur halb umgestellt. Dann hilft es nicht, einfach das alte Image zu nehmen, denn das kennt den neuen Aufbau nicht.

Tunetorch hat vor der Umstellung eine Kopie angelegt:

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

Trag danach in der docker-compose.yml die vorherige Version ein und starte neu. Sonst versucht der neue Server sofort wieder dieselbe Umstellung.

Die Kopie bleibt erhalten, solange die Umstellung scheitert. Tunetorch räumt alte Sicherungen erst weg, wenn ein Update vollständig durchgelaufen ist. Du musst also nicht in Eile handeln, auch wenn der Container weiterläuft und es immer wieder versucht.

Einzelheiten unter Sicherheit & Datensicherung.

Bibliothek

Nach dem Scan ist die Bibliothek leer

Ein Album steht doppelt in der Bibliothek

Der Klassiker: Der Interpret ist in zwei Schreibweisen getaggt („Voxxclub“ und „voXXclub“), und so entstehen zwei Alben.

Der Metadaten-Assistent findet genau das unter Schreibweisen-Dubletten, und beim Zusammenführen verschwindet die Dublette gleich mit. Er gehört zu Pro. Ohne Abo korrigierst du die Schreibweise im Metadaten-Editor, das Zusammenführen passiert dabei genauso. Neue Dubletten entstehen beim Hochladen, Importieren und Scannen nicht mehr: Gibt es den Namen schon in genau einer anderen Schreibweise, nimmt Tunetorch diese.

Ein zusammengesetzter Interpret hat eine eigene, fast leere Karte

„Beth Hart & Joe Bonamassa“ wurde als eigener Interpret angelegt. Löse ihn im Metadaten-Editor als Gemeinschaftsalbum auf. Das Album hängt danach an beiden echten Interpreten, und die überflüssige Karte verschwindet.

Ein Album steht unter „Gemeinschaftsalben“, obwohl es keines ist

Das passiert, wenn der zweite Name bei allen Titeln der Platte in der Interpretenzeile steht. Dann gilt das Album als gemeinsames. Du wolltest aber nur einen Gast auf einzelnen Titeln eintragen?

Dann trag ihn nur dort ein: im Metadaten-Editor über die Spalte Mitw. der jeweiligen Titelzeile, nicht über Für das ganze Album pflegen…, denn das schreibt auf jeden Titel. Einen schon albumweit eingetragenen Namen kannst du dort wieder entfernen. Ob der Gast in der Interpretenzeile steht oder als Zusatz dahinter, spielt für die Einsortierung keine Rolle.

Cover fehlen

Änderungen erscheinen nicht

Die Bibliothek liegt zwischengespeichert auf dem Gerät. Tunetorch fragt beim Start nach Änderungen, wenn der Stand älter als eine Stunde ist, und sobald du zur App zurückkehrst (höchstens alle fünf Minuten). Willst du den neuen Stand sofort: Benutzer-Einstellungen → Erweitert → Datenbank → Datenbank abgleichen.

Im Log steht „database is locked“

Ein langer Schreibvorgang (Scan, Import, Export) hat die Datenbank kurz blockiert. Tunetorch macht zwischen seinen Schreibvorgängen Pausen und wartet bis zu 60 Sekunden, bis die Datenbank wieder frei ist. Einzelne Meldungen sind deshalb harmlos. Häufen sie sich, lass große Läufe nachts laufen.

Wiedergabe

Knackser oder Aussetzer über Bluetooth

Erhöhe die Puffergröße unter Benutzer-Einstellungen → Wiedergabe → Audio-Verarbeitung (Automatisch → 0,3 s → 0,5 s → 0,75 s). Mit einem größeren Puffer reagiert der Equalizer etwas träger, dafür verschwinden die meisten Aussetzer über Bluetooth.

Titel bricht bei schlechter Verbindung ab

Das sollte nicht passieren, weil Tunetorch jeden Titel vor dem Start vollständig lädt. Passiert es trotzdem, schau im Debug-Protokoll nach, ob das Laden abgebrochen ist. Eine niedrigere Qualitätsstufe verringert die Datenmenge.

Die Wiedergabe stoppt, wenn der Bildschirm ausgeht (Android)

In der PWA liegt das am Energiesparmodus des Systems. Es gibt zwei Wege:

  1. Die Android-App verwenden. Sie spielt unabhängig vom Browser und ist davon nicht betroffen.
  2. Dem Browser (nicht der PWA) eine Akku-Ausnahme geben.

Ein Titel hat keine Lautheits-Angleichung

Ihm fehlt der Messwert. Entweder ist die Messung beim Hochladen oder Importieren für diese Datei fehlgeschlagen, oder der Titel stammt aus einem schreibgeschützt eingehängten Ordner, wo beim Einlesen nicht gemessen wird. Meist erledigt sich beides von selbst: Beim nächsten Abspielen misst Tunetorch nach und merkt sich das Ergebnis. Der Titelwechsel dauert dann einmalig etwas länger. Das gilt in App und Browser genauso wie beim Casting.

Willst du nicht warten, bis jeder betroffene Titel einmal dran war, lass den Wartungs-Task Lautheit messen laufen. Er misst alle Titel ohne Wert auf einmal, hochgeladene wie eingehängte. Ab Werk ist er aus, weil er für jede Datei eine vollständige Audio-Analyse rechnet und den Server entsprechend belastet.

App & Auto

„App wurde nicht installiert“ (Installation per APK-Datei)

Das ist Play Protect, das Installationen außerhalb des Stores blockiert. Bestätige den Hinweis („Trotzdem installieren“) oder schalte Play Protect kurz ab. Bei einer Installation aus dem Play Store passiert das nicht.

Ein zweiter möglicher Grund: Test- und Store-Version sind unterschiedlich signiert und lassen sich nicht übereinander installieren. Deinstalliere dann zuerst die alte.

Wo finde ich die Installations-Anleitung?

Unter Einstellungen → Reiter „App“ → Installation. Dort steht genau der Weg, der zu deinem Gerät passt (Android: Play Store, iOS und Rechner: Web-App). In der Android-App fehlt die Rubrik, dort steht stattdessen die App-Version.

Android Auto zeigt Tunetorch nicht an

Wurde die App als APK-Datei installiert (zum Beispiel auf Testgeräten), zeigt Android Auto sie nur an, wenn in den Entwickler-Optionen „Unbekannte Quellen“ aktiviert ist. Bei einer Installation aus dem Play Store ist das nicht nötig.

Im Auto sind alle Listen leer

Dann konnte die App die Bibliothek nicht laden, meistens weil beim Start kein Empfang war (Tiefgarage, Funkloch). In dem Fall steht oben im Reiter ein Eintrag mit dem Namen der Liste und „Konnte nicht geladen werden · Tippen für neuen Versuch". Ein Tipp darauf versucht es noch einmal, und sobald das Handy wieder Empfang hat, lädt die App von selbst nach. Eine abgelaufene Anmeldung erneuert die App dabei selbst mit dem gespeicherten Passwort. Bleibt es leer, prüfe, ob der Server erreichbar ist.

Steht dort „Anmeldung nötig", hat der Server das gespeicherte Passwort abgelehnt, etwa weil du es geändert hast. Öffne die App am Handy: Sie zeigt direkt die Bearbeitung der Verbindung. Trag dort das neue Passwort ein. Erst dann kann sich die App im Auto wieder selbst anmelden.

Im Auto bricht eine Liste mitten im Alphabet ab

Android Auto zeigt Listen nur bis zu einer bestimmten Länge an. Tunetorch teilt lange Listen deshalb selbst auf: Ab 200 Einträgen kommt zuerst eine Auswahl nach Anfangsbuchstaben (A · B · C … · #). Ist ein Buchstabe selbst zu voll, folgt eine Auswahl nach dem zweiten Buchstaben (Sa · Sb · Sc …). Playlists und „zuletzt gehört"-Listen werden in Abschnitte geteilt („1–200" …). Siehst du diese Aufteilung nicht, ist deine App zu alt. Aktualisiere sie.

In der App fehlen Reiter oder Menüpunkte

Der Reiter App zeigt nur in der Android-App die Speicher (Audio-Cache, Downloads, Cover-Cache). Im Browser steht dort stattdessen die Installations-Anleitung. Und im Offline-Modus sind alle Funktionen ausgeblendet, die den Server brauchen (Hochladen, Statistik, Playlists, Bearbeiten, Export). Das erkennst du am Offline-Symbol neben dem Benutzernamen.

Casting

Ich sehe keine Geräteauswahl im Benutzermenü

Dafür müssen drei Dinge erfüllt sein:

  1. Der Master-Schalter unter Server-Einstellungen → DLNA ist an.
  2. Dein Konto hat das Recht DLNA.
  3. Mindestens ein Gerät ist eingetragen und erreichbar.

Das Gerät wird beim Hinzufügen nicht gefunden

Die Wiedergabe startet nicht, obwohl das Gerät da ist

Meistens fehlt die Server-Adresse für die Wiedergabe-Geräte. Sie muss die Adresse deines Servers im Heimnetz samt Port enthalten (http://192.168.1.50:5000), nicht localhost, nicht die IP des Containers und nicht deine öffentliche Domain. Der Lautsprecher holt sich die Musik selbst über diese Adresse.

Das Gerät zeigt Interpret und Album nicht an

Tunetorch schickt alle Angaben mit, aber ob ein Gerät sie anzeigt, entscheidet seine Firmware. Geschlossene Systeme zeigen bei fremder Steuerung oft nur Titel und Cover. Daran können wir leider nichts ändern.

CD rippen

Der Menüeintrag „CD rippen" fehlt

Er erscheint nur, wenn es etwas zu tun gibt: Das CD-Rippen ist in den Server-Einstellungen eingeschaltet, dein Konto hat das Recht Audio-CDs rippen (oder ist Admin), und in einem zum Rippen freigegebenen Laufwerk liegt eine Audio-CD — oder du hast gelesene CDs, die noch auf die Übernahme warten. Eine Daten-CD oder ein leeres Laufwerk zählt nicht. Steht das Laufwerk in den Server-Einstellungen nur unter Erkannte Laufwerke, fehlt die Freigabe. Eine gerade eingelegte CD erscheint, wenn du das Menü das nächste Mal öffnest. Sieht der Server gar kein Laufwerk, fehlt meistens die Zeile /dev:/dev in der Compose-Datei (CD-Laufwerk durchreichen). Auf einer Synology NAS fehlt dagegen meist der Treiber für das Laufwerk (Synology NAS (DSM)).

„Kein Zugriff auf das Laufwerk"

Der Server sieht das Laufwerk, darf es aber nicht öffnen. Fast immer stimmt die Zahl bei group_add nicht. Sie muss die Gruppe sein, der /dev/sr0 auf dem Host gehört (stat -c '%g' /dev/sr0). Nach der Änderung erstellst du den Container neu (docker compose up -d).

Titel bleiben „konsistent", werden aber nie „verifiziert"

Entweder kennt AccurateRip die CD nicht (bei seltenen Pressungen ist das normal), oder der Lese-Offset des Laufwerks fehlt oder ist falsch. Lass ihn in den Server-Einstellungen mit einer weit verbreiteten CD automatisch erkennen. Meldet die Erkennung „mehrere Pressungen“, leg eine andere CD ein und starte sie noch einmal.

Der Rip bricht immer wieder ab, das Laufwerk verschwindet

Auf einem Raspberry Pi liegt das fast immer an der Stromversorgung. Das Laufwerk braucht beim Anlaufen mehr Strom, als die USB-Buchsen liefern. Ein Laufwerk mit eigenem Netzteil oder ein aktiver USB-Hub behebt das. Schon gelesene Titel gehen dabei nicht verloren. Mit derselben CD liest Fortsetzen nur die fehlenden nach.

Startet der Pi von einer USB-SSD, kann statt des Laufwerks auch der ganze Pi hängen bleiben. Er antwortet dann noch auf Ping, aber nicht mehr auf SSH. Häng das Laufwerk an einen aktiven Hub und lass die SSD direkt am Pi (CD-Laufwerk durchreichen).

Logs finden

Der eingebaute Log-Viewer (Server-Einstellungen → Logs) zeigt die letzte Stunde bis 28 Tage, filterbar nach Quelle und Level. Von außen kommst du so an die Logs:

docker compose logs -f tunetorch

Brauchst du mehr Details, setzt du TT_LOG_LEVEL vorübergehend auf DEBUG.

Jede Zeile beginnt mit einem Code wie [TT-DLNA-012]. Er ist in beiden Log-Sprachen derselbe (Server-Einstellungen → Sprache der Server-Logs), und über ihn lässt sich eine Zeile nachschlagen.

Nichts davon hilft?

Schreib uns über das Kontaktformular (Rubrik Fehlermeldung) oder komm auf den Discord-Server. Dort gibt es ein Support-Forum, in dem du deine Frage nach Plattform einsortierst (Docker, NAS, Raspberry Pi, Android, Web-Player, DLNA). Hilfreich sind:

Zurück zur Dokumentations-Übersicht