Fehlerbehebung

Die häufigsten Stolpersteine — jeweils mit dem, was tatsächlich dahintersteckt.

Anmeldung

Die Anmeldung schlägt fehl, obwohl das Passwort stimmt

Fast immer ein Cookie-Problem durch die falsche HTTPS-Einstellung.

Tunetorch geht standardmäßig davon aus, hinter einem TLS-Reverse-Proxy zu laufen, und setzt seine Anmelde-Cookies mit dem Secure-Flag. Rufst du es direkt per HTTP auf, verwirft der Browser sie — die Anmeldung scheint fehlzuschlagen, obwohl der Server sie akzeptiert hat.

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

Danach den Container neu erstellen — ein einfacher Neustart übernimmt geänderte Umgebungsvariablen nicht:

docker compose up -d

Zur Gegenprobe das Server-Log ansehen (docker logs tunetorch): Bei falscher Einstellung steht dort direkt hinter dem Anmeldeversuch die Zeile TT_HTTPS=True, aber der Login-Request kam über HTTP. Ein falsches Passwort sähe anders aus — dann stünde dort Login fehlgeschlagen: Ungültige Anmeldedaten.

Warum es beim Einrichten noch ging: Über http://localhost:5000 akzeptieren Chrome, Edge und Firefox Secure-Cookies trotzdem, weil sie localhost als sicheren Kontext behandeln. Erster Login und Passwortwechsel direkt auf dem Server funktionieren dadurch auch mit falscher Einstellung — erst der Zugriff vom zweiten Gerät über die LAN-Adresse scheitert. Das legt den Verdacht auf das neue Passwort, obwohl es daran nicht liegt.

Ich werde nach etwa 15 Minuten immer wieder abgemeldet

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

Zwei Ursachen kommen infrage:

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

Lösung in beiden Fällen: Website-Cookies löschen und neu anmelden. Damit das 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 → 60 Minuten Sperre). Warte die Sperrdauer ab oder passe die Werte in den Server-Einstellungen an.

Sperrt es alle gleichzeitig aus? Dann sieht der Server nur die IP deines Reverse-Proxys. Setze TT_TRUSTED_PROXIES auf die Zahl der vorgeschalteten Proxies (üblicherweise 1).

Niemand kommt mehr in die Verwaltung

Ist das Passwort des einzigen Admin-Kontos verloren, lässt es sich auf dem Server zurücksetzen — direkt im laufenden Container:

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

Was der Befehl tut, was er bewusst nicht tut und warum er kein Sicherheitsloch 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. Der Container versucht beim Start, das Verzeichnis der eingestellten UID:GID zu übereignen; schlägt das fehl (Read-only-Dateisystem, ACLs), bricht er bewusst ab, statt später halb zu funktionieren.

Prüfe die Eigentümer auf dem Host:

ls -ln ./tunetorch-daten

und setze TT_PUID/TT_PGID entsprechend. Auf Synology DSM ist das oft 1026:100; kommt zusätzlich eine ACL ins Spiel, gib dem Benutzer mit dieser UID in der File Station explizit 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 Prozess nicht mehr — ein Neustart hilft, die Ursache steht im Log. Zeigt er healthy, liegt es eher an Port-Weiterleitung oder Reverse-Proxy.

Nach einem Update fehlt etwas

Schema-Änderungen zieht Tunetorch beim Start selbst nach. Sieh ins Log, ob die Migration durchgelaufen ist. Prüfe außerdem im Server-Status, welche Version tatsächlich läuft — ein docker compose up -d ohne vorheriges pull startet unter Umständen das alte Image erneut.

Nach einem Update startet der Server nicht mehr

Steht im Log eine gescheiterte Schema-Migration, ist die Datenbank möglicherweise nur zur Hälfte umgestellt. Der Rückgriff auf das alte Image allein hilft dann nicht — es kennt das veränderte Schema 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

Danach in der docker-compose.yml die vorherige Version eintragen und neu starten — sonst versucht der neue Server dieselbe Umstellung sofort wieder.

Die Kopie wird nicht überschrieben, 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

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

Der Metadaten-Assistent findet genau das unter Schreibweisen-Dubletten; das Zusammenführen räumt die Dublette gleich mit auf. Er gehört zu Pro — ohne Abo korrigierst du die Schreibweise im Metadaten-Editor, das Zusammenführen passiert dabei genauso.

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 Kunst-Karte verschwindet.

Cover fehlen

Änderungen erscheinen nicht

Die Bibliothek liegt gerätelokal im Cache und wird stündlich im Hintergrund erneuert. Willst du sofort den neuen Stand: Benutzer-Einstellungen → Erweitert → Datenbank → Datenbank abgleichen.

Im Log steht „database is locked“

Ein langer Schreibvorgang (Scan, Import, Export) hat die Datenbank blockiert. Tunetorch legt zwischen seinen Schreibblöcken bewusst Pausen ein und wartet bis zu 60 Sekunden auf Freigabe — gelegentliche Meldungen sind unkritisch. 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 → Erhöht → Hoch → Maximal). Ein größerer Puffer kostet etwas Reaktionslatenz beim Equalizer, beseitigt aber die meisten Bluetooth-Aussetzer.

Titel bricht bei schlechter Verbindung ab

Sollte nicht passieren — Tunetorch lädt jeden Titel vor dem Start vollständig. Tritt es trotzdem auf, prüfe im Debug-Protokoll, ob der Ladevorgang abgebrochen wurde. Eine niedrigere Qualitätsstufe verkleinert die zu übertragende Datenmenge.

Die Wiedergabe stoppt, wenn der Bildschirm ausgeht (Android)

In der PWA ist das der Energiesparmodus des Systems. Zwei Wege:

  1. Die native App verwenden — sie hält die Wiedergabe in einem Vordergrund-Dienst 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. Zwei Ursachen: Die Messung beim Hochladen oder Importieren ist für diese Datei fehlgeschlagen — oder der Titel stammt aus einem read-only eingehängten Ordner, denn beim Einlesen wird nicht gemessen. Beides erledigt sich in der Regel 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 erfasst alle Titel ohne Werte auf einmal, hochgeladene wie eingehängte. Er ist standardmäßig ausgeschaltet, weil er dabei die volle Rechenlast einer Audio-Analyse je Datei erzeugt.

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 deaktiviere Play Protect kurzzeitig. Aus dem Play Store installiert, tritt das nicht auf.

Zweite mögliche Ursache: Debug- und Release-Version tragen unterschiedliche Signaturen und lassen sich nicht übereinander installieren — die alte zuerst deinstallieren.

Wo finde ich die Installations-Anleitung?

Unter Einstellungen → Reiter „App“ → Installation. Der Reiter zeigt genau den Weg, der zu deinem Gerät passt (Android: Play Store, iOS/Desktop: Web-App). In der nativen App fehlt die Rubrik — dort steht stattdessen die App-Version.

Android Auto zeigt Tunetorch nicht an

Wurde die App per APK-Datei installiert (Testgeräte), zeigt Android Auto sie nur mit aktivierter Entwickler-Option „Unbekannte Quellen“. Aus dem Play Store installiert, entfällt das.

Im Auto sind alle Listen leer

Dann konnte die App die Bibliothek nicht laden — meist, weil beim Start kein Empfang war (Tiefgarage, Funkloch). Ab App-Version 1.17.0 steht in diesem Fall der Eintrag „Bibliothek konnte nicht geladen werden" im Auto; ein Tipp darauf startet einen neuen Versuch, und sobald das Gerät wieder Empfang hat, lädt die App von selbst nach. Bleibt es leer, prüfe, ob du in der App noch angemeldet bist und der Server erreichbar ist.

Im Auto bricht eine Liste mitten im Alphabet ab

Das war ein Fehler in älteren App-Versionen: Android Auto nimmt eine Liste nur bis zu einer festen Größe entgegen und schnitt den Rest wortlos ab — bei einer großen Bibliothek endete die Interpreten-Liste dann etwa mitten im Buchstaben B, und die Buchstaben-Vorwahl am Rand kannte folgerichtig auch nur A und B.

Seither teilt Tunetorch lange Listen selbst auf: Ab 200 Einträgen kommt zuerst eine Buchstaben-Auswahl (A · B · C … · #), bei Playlists und den „zuletzt gehört"-Listen Blöcke („1–200" …). Siehst du das nicht, ist die App zu alt — aktualisieren.

In der App fehlen Reiter oder Menüpunkte

Der Reiter App existiert nur in der nativen Android-App, nicht im Browser. Und im Offline-Modus sind alle Server-Funktionen (Hochladen, Statistik, Playlists, Bearbeiten, Export) ausgeblendet — erkennbar am Offline-Symbol neben dem Benutzernamen.

Casting

Ich sehe kein Ziel-Menü im Player

Drei Voraussetzungen müssen 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 registriert und erreichbar.

Das Gerät wird beim Hinzufügen nicht gefunden

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

Meist fehlt die Server-Adresse für die Wiedergabe-Geräte. Sie muss die LAN-Adresse deines Hosts samt Port enthalten (http://192.168.1.50:5000) — nicht localhost, nicht die Container-IP und nicht deine öffentliche Domain. Der Lautsprecher zieht die Musik selbst über diese Adresse.

Das Gerät zeigt Interpret und Album nicht an

Tunetorch schickt alle Metadaten mit; ob ein Renderer sie darstellt, entscheidet seine Firmware. Bei geschlossenen Systemen erscheinen bei Fremd-Steuerung oft nur Titel und Cover. Das lässt sich von unserer Seite nicht beheben.

Logs finden

Der eingebaute Log-Viewer (Server-Einstellungen → Logs) zeigt die letzten Stunde bis 28 Tage, filterbar nach Quelle und Level. Für den Blick von außen:

docker compose logs -f tunetorch

Für mehr Details lässt sich TT_LOG_LEVEL vorübergehend auf DEBUG setzen.

Nichts davon hilft?

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

Zurück zur Dokumentations-Übersicht