Jellyfin-Datenbank gerettet: Wie defekter RAM meine SQLite-DB zerlegt hat
Mein Jellyfin-Server läuft als Docker-Container (Jellyfin 10.11) auf einem Debian-Host. Seit einiger Zeit fühlte sich alles zäh an, und im Log tauchten bei jeder Wiedergabe Fehler wie diese auf:
[ERR] Microsoft.EntityFrameworkCore.Database.Command: Failed executing DbCommand (30,110ms) ...
[ERR] JellyfinDbContext: Error trying to save changes.
[ERR] ExceptionMiddleware: Error processing request. URL POST /Sessions/Playing/Progress.
Ein UPDATE, das nach 30 Sekunden in den Timeout läuft, sieht zuerst nach einer gesperrten Datenbank aus. Die Folge für die Nutzer: Die Wiedergabeposition wurde nicht mehr zuverlässig gespeichert. Repariert habe ich das zusammen mit Claude Code, direkt per SSH auf dem Server. Am Ende stellte sich heraus, dass das Problem gar nicht in der Software lag, und zum Abschluss gab es noch das Upgrade auf Jellyfin 12.4. Aber der Reihe nach.
Teil 1: Die beschädigte Datenbank
Im kompletten Tageslog stand neben den Timeouts dutzendfach SQLite Error 11: database disk image is malformed. Die Sperren waren nur eine Folge davon. Und der Schaden war alt: Mein Wartungsskript hatte schon Monate vorher beim Integrity-Check abgebrochen. Das ist nur niemandem aufgefallen, weil das Skript still aufgibt.
Schritt 1: Diagnose an einer Kopie
Grundregel: An der Live-Datenbank wird erst einmal nichts verändert. Mit der Online-Backup-Funktion von SQLite lässt sich eine konsistente Kopie ziehen, während Jellyfin weiterläuft. Auf dieser Kopie lief dann der Integrity-Check:
sqlite3 jellyfin.db ".backup /tmp/check/live.db"
sqlite3 /tmp/check/live.db "PRAGMA integrity_check(100000);"
On tree page 190688 cell 33: Rowid 769432 out of order
On tree page 179786 cell 33: Rowid 303930 out of order
On tree page 237163 cell 74: Extends off end of page
row 289582 missing from index IX_PeopleBaseItemMap_PeopleId
...
Über die virtuelle Tabelle dbstat kann man nachsehen, zu welcher Tabelle eine defekte Seite gehört:
SELECT pageno, name FROM dbstat WHERE pageno IN (190688, 179786, 237163);
237163|sqlite_autoindex_BaseItemImageInfos_1
179786|PeopleBaseItemMap
190688|PeopleBaseItemMap
Das war eine gute Nachricht. Betroffen waren die Tabelle PeopleBaseItemMap, die nur Schauspieler und Crew mit Filmen und Serien verknüpft, und ein Index. Benutzer, Watch-Status und Bibliotheken waren nicht beschädigt.
Schritt 2: Warum REINDEX und .recover nicht reichten
- REINDEX reparierte den kaputten Index von
BaseItemImageInfos. Defekte Tabellenseiten kann es aber nicht reparieren. - Tabelle umkopieren per
INSERT ... SELECTbrach genau an den defekten Seiten ab. - .recover lieferte eine leere Datei. Das sqlite3 aus Debian 12 ist ohne
sqlite_dbpagegebaut, und.recoverbraucht genau das. Das Tückische: Im Hintergrund ausgeführt, sieht man nur eine 0-Byte-Datei und keine Fehlermeldung.
Schritt 3: Daten blockweise bergen
Der Trick: Ein Full Table Scan stirbt an der ersten kaputten Seite. Eine Abfrage über einen rowid-Bereich navigiert dagegen über den B-Baum gezielt zu den passenden Seiten und kann defekte Bereiche umgehen. Ein kleines Python-Skript liest die Tabelle deshalb in Blöcken von 5000 Zeilen. Schlägt ein Block fehl, wird er halbiert, bis nur noch die einzelnen unlesbaren Zeilen übrig bleiben:
def grab(a, b):
try:
rows.extend(db.execute(
"SELECT rowid, * FROM PeopleBaseItemMap NOT INDEXED "
"WHERE rowid BETWEEN ? AND ?", (a, b)).fetchall())
except sqlite3.DatabaseError:
if a == b:
lost.append(a); return
m = (a + b) // 2
grab(a, m); grab(m + 1, b)
Ergebnis: Von rund 780.000 Zeilen waren nur 2 unlesbar. Danach habe ich den Tabelleneintrag per writable_schema aus dem Schema entfernt und ein VACUUM laufen lassen, damit die defekten Seiten aus der Datei verschwinden. Anschließend habe ich die Tabelle mit Originalschema und Indizes neu angelegt und die geretteten Zeilen eingefügt.
Schritt 4: Die versteckte zweite Baustelle
Der nächste Integrity-Check zeigte Fehler in BaseItemProviders, also bei den TMDB- und TVDB-IDs. Der erste Check hatte diese Tabelle nie erreicht, weil er beim ersten malformed abgebrochen war. Ein Lehrstück: Ein abgebrochener Integrity-Check ist kein vollständiger Befund.
Der Primärschlüssel-Index war kaputt, und genau deshalb hatten sich Dubletten eingeschlichen, die der Index nicht mehr verhindert hat. Auch ein GROUP BY fand sie zunächst nicht, weil es den kaputten Index benutzte. Die Lösung war ein Neuaufbau, der die Tabelle ohne Index liest und bei Dubletten die älteste Zeile behält:
INSERT OR IGNORE INTO BaseItemProviders_new
SELECT ItemId, ProviderId, ProviderValue
FROM BaseItemProviders NOT INDEXED ORDER BY rowid;
Danach meldete PRAGMA integrity_check endlich ok.
Schritt 5: Der Tausch
Weil Jellyfin während der Tests weitergelaufen war, habe ich die komplette Reparatur für den Tausch noch einmal auf dem aktuellen Stand ausgeführt, als Skript mit eingebauter Notbremse:
- Jellyfin und das Zusatztool, das auf das Config-Verzeichnis zugreift, stoppen.
- Die defekte DB sichern und die Kopie per
cmpbitgenau verifizieren. - Bergung, Deduplizierung und
VACUUMauf einer Kopie ausführen. - Nur wenn der Integrity-Check exakt
okliefert, die neue DB einsetzen. Andernfalls startet Jellyfin wieder mit der alten DB. - Container starten und das Log prüfen.
Die Ausfallzeit lag bei rund fünf Minuten. Jellyfin startete in elf Sekunden, und die DB-Fehler waren verschwunden. Ich dachte, das war’s.
Teil 2: Das Backup, das nicht wollte
Zur Sicherheit habe ich danach gleich ein Backup über die eingebaute Backup-Funktion von Jellyfin angestoßen. Es brach nach wenigen Sekunden ab:
[INF] BackupService: Begin backup of entity BaseItems
[ERR] Microsoft.EntityFrameworkCore.Query: An exception occurred while iterating over the results of a query
System.FormatException: Guid string should only contain hexadecimal characters.
[ERR] BackupService: Failed to create backup, removing .../jellyfin-backup-....zip
Jellyfin 10.11 speichert IDs als GUID-Text. Beim Backup wird jede Zeile eingelesen, und eine einzige GUID mit einem Zeichen außerhalb von 0–9 und A–F reicht für den Abbruch. Mit der Reparatur hatte das nichts zu tun, denn dieselben Fehler steckten auch schon in der alten DB. SQLite selbst stört sich nicht daran. Für die Datenbank ist das einfach Text, und deshalb meldet integrity_check hier auch nichts.
Schritt 6: Alle GUIDs der Datenbank prüfen
Ein Python-Skript läuft über alle Tabellen und sucht Spalten, die überwiegend GUIDs enthalten, aber einzelne ungültige Werte haben. Wichtig dabei: Die Werte müssen per CAST(... AS BLOB) gelesen werden. Manche Einträge sind kein gültiges UTF-8 mehr, und Pythons sqlite3-Modul scheitert sonst schon beim Lesen.
Gefunden wurden gut 40 kaputte Werte, verteilt auf die Besetzungstabelle, die Stream-Infos und ein paar Medien-Einträge. Spannend wurde es beim genauen Hinsehen:
...-7D74UB83... statt ...-7D74EB83... E (0x45) -> U (0x55)
...-1R96-... statt ...-1B96-... B (0x42) -> R (0x52)
...-5E22-)172... statt ...-5E22-9172... 9 (0x39) -> ) (0x29)
...-84C6=4DE4... statt ...-84C6-4DE4... - (0x2D) -> = (0x3D)
Fast jeder Fehler unterscheidet sich vom richtigen Zeichen in genau einem Bit. Das ist das typische Muster von Bitflips. Den endgültigen Beweis lieferte ausgerechnet eine Star-Trek-Folge: In derselben Zeile wie die kaputte Staffel-ID stand als Serienname Star Trek: Baumschiff Voyaggr. R wurde zu B und e zu g, wieder jeweils ein einziges Bit.
Weil sich Bitflips so gut eingrenzen lassen, konnte das Skript viele Werte sogar zurückrechnen: Es kippt jedes Bit einzeln zurück und schaut, ob dabei eine ID herauskommt, die es in der Datenbank wirklich gibt. Bei der Staffel-ID gab es genau einen Treffer, nämlich Staffel 4 von Voyager.
Schritt 7: Bereinigen
Wieder mit Stopp, bitgenauer Sicherung und anschließendem Integrity-Check:
- Staffel-ID und Serienname der Voyager-Folge korrigiert, weil es einen eindeutigen Treffer gab.
- 34 Besetzungs-Verknüpfungen und 3 Stream-Infos gelöscht. Beides erzeugt Jellyfin beim nächsten Scan beziehungsweise Metadaten-Refresh neu. Das ist sicherer als eine Korrektur, die zufällig zu einem falschen Eintrag passen könnte.
- 6 Verweise auf das Eltern-Item bei Sample-Videos geleert. Hier waren die Bytes so zerstört, dass nichts mehr zu retten war.
Danach fand der GUID-Scan keine ungültigen Werte mehr, der Integrity-Check meldete ok, und das Jellyfin-Backup lief endlich durch.
Die eigentliche Ursache: defekter Arbeitsspeicher
Gekippte Bits mitten in Datensätzen sind kein Softwarefehler. Sie entstehen, wenn Hardware Daten verfälscht, bevor sie auf die Platte geschrieben werden, meistens im RAM. Genau das war es: Der Arbeitsspeicher des Servers war defekt und ist inzwischen getauscht. Damit erklärt sich auch Teil 1. Ein einziges gekipptes Bit in einem Seitenzeiger oder einer Zellengröße reicht, damit SQLite eine B-Baum-Seite für kaputt hält.
Der Tausch sorgt dafür, dass nichts Neues mehr kaputtgeht. Was vorher geschrieben wurde, bleibt aber verfälscht. Erkennen lassen sich nur Bitflips, die ein ungültiges Zeichen erzeugen. Ein Flip, der aus einer Hex-Ziffer wieder eine gültige Hex-Ziffer macht, oder ein Tippfehler im Titel fällt keiner Prüfung auf. Deshalb kommt zum Abschluss noch ein vollständiger Metadaten-Refresh mit Alle Metadaten ersetzen, der Titel, IDs und Besetzung frisch von den Quellen holt.
Teil 3: Das Upgrade auf Jellyfin 12.4
Mit einer sauberen Datenbank und einem funktionierenden Backup war der Moment günstig, endlich von 10.11.10 auf die aktuelle Version zu gehen. Das ist ein großer Sprung: Jellyfin 12.0 baut die Datenbank deutlich um, und ein Zurück gibt es danach nur noch über ein vollständiges Backup.
Der Upgrade-Pfad
Laut den Release Notes von 12.0 ist der Sprung von 10.10.7 oder einer beliebigen 10.11.x direkt auf 12.x unterstützt. Ein Zwischenschritt über 10.11.11 ist nicht nötig, also ging es direkt auf 12.4. Vorher habe ich die Voraussetzungen aus den Release Notes geprüft:
- Benutzernamen: 12.0 legt einen eindeutigen Index auf normalisierte Benutzernamen. Namen, die sich nur in Groß- und Kleinschreibung unterscheiden, blockieren das Upgrade. Bei mir gab es keine.
- Plugins: Alle Plugins aus Repositories sollen vor der Migration entfernt werden. Ich habe die Plugin-Ordner nur aus dem Plugin-Verzeichnis verschoben, statt sie zu deinstallieren. So bleiben ihre Daten erhalten, und ich kann sie später in 12.x-kompatiblen Versionen neu installieren.
- Alte API-Routen:
/emby/*und/mediabrowser/*fallen weg, und die Legacy-Authentifizierung wird abgeschaltet. Ein Blick ins Log der letzten 24 Stunden zeigte keinen Client, der diese Routen noch benutzt. - GUIDs: 12.0 macht
OwnerIdzu einem echten Fremdschlüssel. Mit den kaputten Werten aus Teil 2 wäre genau diese Migration gescheitert. Die Reparatur davor war also auch die Vorbereitung fürs Upgrade.
Durchführung
- Jellyfin und das Zusatztool stoppen.
- Ein Vollbackup des kompletten Config-Verzeichnisses als tar-Archiv anlegen, ohne die Transcoding-Dateien.
- Die Plugin-Ordner auslagern.
- In der
docker-compose.ymldas Image auf eine feste Version setzen, nicht auflatest. So springt ein automatischer Updater wie Watchtower nicht unkontrolliert auf die nächste Major-Version. - Container neu erstellen und die Migration im Log verfolgen.
image: linuxserver/jellyfin:12.4ubu2604-ls60
# image: linuxserver/jellyfin:10.11.10
Die Migration
Jellyfin legt vor der Migration selbst eine Sicherung der DB an und arbeitet dann 36 Migrationen in drei Phasen ab. Die Schema-Änderungen waren nach rund 40 Sekunden durch, auch ChangeOwnerIdToGuid und AddForeignKeyToOwnerId. Den Großteil der Zeit brauchten die Aufräum-Routinen, die rund 190.000 Items gegen das Dateisystem prüfen und verwaiste Bilder suchen. Bei einer Bibliothek, die per rclone eingebunden ist, dauert das. Nach 23 Minuten stand im Log:
[INF] Main: Jellyfin version: 12.4.0
...
[INF] MigrateLinkedChildren: Removed 45 stale items.
[INF] FixIncorrectOwnerIdRelationships: Successfully removed 4 duplicate database entries
[INF] MergeDuplicatePeople: Removed 47 duplicate Peoples rows.
...
[INF] Main: Startup complete 0:23:21.2485291
Auch hier zeigten sich noch Spuren der Bitflips: Bei 4 von rund 52.000 Items war gespeicherter JSON-Text kaputt, etwa mit der Meldung 'E' is invalid after a property name. Die Migration hat diese Einträge mit einer Warnung übersprungen statt abzubrechen. Der nächste Bibliotheks-Scan baut sie neu auf. Fehler gab es keine, und das Zusatztool zur Benutzerverwaltung konnte sich sofort wieder an der neuen Version anmelden.
Nach dem Upgrade
- Vollständiger Bibliotheks-Scan, und zwar Pflicht: 12.0 entfernt automatisch zusammengeführte alternative Versionen von Filmen, der Scan stellt sie wieder her. Der erste Scan dauert deutlich länger als sonst. Ich verbinde ihn gleich mit dem Metadaten-Refresh gegen die restlichen Bitflip-Schäden.
- Plugins neu installieren, und zwar aus dem stabilen Repository in Versionen für 12.x.
- Aufräumen, sobald alles ein paar Tage stabil läuft: das Vollbackup und die vielen alten DB-Kopien.
Bilanz
- Benutzer, Watch-Status, Items, Bilder und Kapitel: vollständig erhalten.
- Besetzung: rund 40 von etwa 780.000 Verknüpfungen entfernt. Ein Refresh holt sie zurück.
- Provider-IDs: 2 widersprüchliche Dubletten bereinigt.
- Stream-Infos: 3 Einträge entfernt, werden neu eingelesen.
- Jellyfin-Backup: läuft wieder.
- Version: von 10.11.10 auf 12.4.0.
- Ausfallzeit: unter zehn Minuten für die Reparatur, dazu rund 45 Minuten für Vollbackup und Migration beim Upgrade.
Was ich daraus mitnehme
- Timeouts und locked sind oft nur das Symptom. Erst einmal das ganze Log nach malformed durchsuchen.
- Wiederkehrende Datenbank-Korruption ist ein Hardware-Verdacht. Wenn eine SQLite-DB immer wieder kaputtgeht, lohnt sich ein Memtest, bevor man die nächste Reparatur startet.
- Bitflips erkennt man am Muster. Falsches und richtiges Zeichen nebeneinander, XOR rechnen: Bleibt genau ein Bit übrig, ist die Hardware schuld.
- integrity_check ist nicht alles. Er prüft die Struktur, nicht den Inhalt. Und wenn er vorzeitig abbricht, ist auch die Strukturprüfung unvollständig.
- Erst reparieren, dann upgraden. Die Migrationen auf 12.x sind strenger und hätten an genau den kaputten Daten aufgegeben, die vorher niemandem aufgefallen waren.
- Major-Upgrades nie über latest. Die Version fest setzen, die Release Notes lesen, die Voraussetzungen prüfen und vorher ein Vollbackup anlegen.
- Wartungsskripte müssen laut scheitern. Ein Eintrag in eine Logdatei, die niemand liest, ist keine Warnung.
- Immer an Kopien arbeiten, und vor jeder Änderung eine bitgenaue Sicherung anlegen.
- Debian-sqlite3 kann kein .recover. Wer es braucht, nimmt ein aktuelles SQLite oder geht den Weg über rowid-Bereiche.
Sei der erste!
Schreibe mir