JTL-Shop-Update abgebrochen oder zurückgerollt: hängende Migrationen erkennen und das Update sauber abschließen

Ein JTL-Shop-Update ist eigentlich ein zweistufiger Vorgang: Zuerst werden die neuen Programmdateien eingespielt, danach passt das Datenbank-Update die Tabellen an die neue Version an. Solange beide Schritte vollständig durchlaufen, merken Sie davon wenig. Bricht einer davon ab oder wird nur einer davon rückgängig gemacht, stehen Dateien und Datenbank auf unterschiedlichem Stand – und der Shop reagiert mit weißer Seite, Fatal Error oder einer Wartungsseite.

Dieser Artikel zeigt, wie Sie diesen Zustand erkennen, was im Hintergrund passiert und wie Sie das Update sauber zu Ende bringen.

Typische Symptome

Die folgenden Fehlerbilder treten in der Praxis immer wieder auf:

• Weiße Seite oder Fatal Error im Frontend direkt nach dem Hochladen der neuen Dateien.
• Hinweis im Backend, dass ein Datenbank-Update erforderlich ist – auch dann, wenn Sie gar nicht aktualisieren wollten, sondern gerade auf die alte Version zurückgegangen sind.
• Das Datenbank-Update im Admin bricht ab, ohne verständliche Meldung. Im Browser (Entwicklertools, Reiter „Netzwerk“) sieht man dann nur eine Anfrage an /admin/io, die mit einem leeren Fehler 500 antwortet.
• Fehlermeldungen zu unbekannten Konstanten oder Klassen, zum Beispiel Undefined constant "LINKTYP_ACCESSIBILITY".

Der letzte Punkt ist besonders aufschlussreich: Die Konstante LINKTYP_ACCESSIBILITY gibt es nur in neueren Shop-Versionen. Taucht sie in einem Shop auf, der gerade auf einer älteren Version laufen soll, versucht dieser offensichtlich Code aus einer neueren Version auszuführen.

Warum das passiert: Dateien und Datenbank laufen auseinander

JTL-Shop 5 verwaltet Änderungen an der Datenbank über sogenannte Migrationen. Jede Migration ist eine eigene PHP-Datei im Verzeichnis includes/src/Migrations/, ihr Name enthält einen Zeitstempel, etwa Migration20250902115834.php. Welche Migrationen bereits ausgeführt wurden, merkt sich der Shop in der Tabelle tmigration. Die Version der Datenbank selbst steht in der Tabelle tversion.

Beim Start vergleicht der Shop beide Seiten: Alle Migrationsdateien im Verzeichnis, die noch nicht in tmigration eingetragen sind, gelten als offen. Gibt es offene Migrationen, verlangt der Shop ein Datenbank-Update. Daraus ergeben sich zwei typische Fehlerszenarien.

Szenario 1: Dateien neu, Datenbank alt

Die neuen Dateien wurden hochgeladen, das Datenbank-Update im Backend wurde aber nie gestartet oder ist abgebrochen. Die Programmdateien erwarten Tabellen und Spalten, die es noch nicht gibt. Ergebnis ist meist eine weiße Seite im Frontend, während tversion noch die alte Versionsnummer zeigt.

Dieser Fall ist der harmlosere. In einem Projekt mit Update von 5.2.6 auf 5.7.2 genügte es, das Datenbank-Update im Adminbereich (/admin/dbupdater) vollständig durchlaufen zu lassen. Danach stand tversion auf 5.7.2 und das Frontend lief wieder.

Szenario 2: Dateien zurückgerollt, Datenbank bleibt neu

Schwieriger wird es, wenn nach einem misslungenen Update nur die Dateien auf die alte Version zurückgespielt werden. Dabei passiert oft Folgendes: Das alte Paket wird über die vorhandenen Dateien kopiert. Dateien, die es in der alten Version nicht gab, werden dabei nicht gelöscht – darunter auch die neuen Migrationsdateien.

Der Shop sieht dann Migrationsdateien aus der neueren Version, die in tmigration fehlen, hält sie für offen und versucht sie auszuführen. Diese Migrationen greifen aber auf Konstanten und Klassen zu, die der alte Programmcode nicht kennt. Genau so entsteht der oben beschriebene Fatal Error zu LINKTYP_ACCESSIBILITY. Die Migration, in der diese Konstante verwendet wird, liegt im Quellcode erst in einer späteren Version vor.

Diagnose: Welche Seite steht wo?

Bevor Sie etwas ändern, verschaffen Sie sich ein klares Bild. Alle folgenden Schritte lesen nur.

1. Echte Fehlermeldung holen. Das Backend zeigt bei abgebrochenen Datenbank-Updates oft nur einen leeren Fehler. Den vollständigen Text finden Sie im PHP-Fehlerprotokoll Ihres Hosters und im Ordner jtllogs im Shop-Verzeichnis.

2. Version der Datenbank prüfen. In phpMyAdmin oder einem anderen SQL-Werkzeug:

SELECT nVersion, nFehler, cFehlerSQL, dAktualisiert
  FROM tversion;

nVersion zeigt den Stand der Datenbank. Ist nFehler größer als 0, ist ein früheres Datenbank-Update mit Fehler stehen geblieben; cFehlerSQL enthält dann die zugehörige Meldung.

3. Zuletzt ausgeführte Migrationen ansehen:

SELECT kMigration, nVersion, dExecuted
  FROM tmigration
 ORDER BY kMigration DESC
 LIMIT 10;

Die oberste Zeile ist die zuletzt ausgeführte Migration. Ihre ID ist der Zeitstempel aus dem Dateinamen.

4. Mit den Dateien vergleichen. Sehen Sie im Verzeichnis includes/src/Migrations/ nach, welche Migrationsdatei die höchste Nummer trägt. Ist die höchste Datei neuer als die letzte Zeile in tmigration, gibt es offene Migrationen. Zusätzlich lohnt der Blick in die Tabelle tmigrationlog, in der der Shop Erfolg oder Fehlschlag einzelner Migrationen protokolliert.

5. Version der Dateien feststellen. Vergleichen Sie, welche Shop-Version Sie hochgeladen bzw. zurückgespielt haben, mit nVersion aus tversion. Passen beide nicht zusammen, haben Sie die Ursache gefunden.

Die Lösung: Sichern, entscheiden, vorwärts gehen

Schritt 1: Vollständige Sicherung

Bevor Sie irgendetwas ändern, sichern Sie die Shop-Dateien und die Datenbank, und zwar im aktuellen, defekten Zustand. Das klingt widersinnig, ist aber Ihre einzige Rückfallebene, falls der nächste Schritt Probleme macht.

Ein Backup nur der Dateien oder nur der Datenbank reicht nicht. Genau dieses halbe Zurückspielen hat den Fehler in Szenario 2 ja erst verursacht.

Schritt 2: Richtung festlegen

Es gibt grundsätzlich zwei saubere Wege – und einen unsauberen dazwischen:

• Komplett zurück: Nur möglich, wenn Sie eine Datenbank-Sicherung von vor dem Update besitzen und Dateien und Datenbank gemeinsam auf diesen Stand zurücksetzen. Bestellungen und Kundendaten, die seitdem eingegangen sind, gehen dabei verloren oder müssen gesondert übernommen werden.
• Vorwärts auf die Zielversion (Roll-forward): Sie bringen die Dateien auf die Version, auf der die Datenbank bereits steht oder die Sie ursprünglich erreichen wollten, und lassen das Datenbank-Update vollständig durchlaufen.
• Halb zurück: alte Dateien, neue Datenbank. Diesen Zustand sollten Sie nicht dauerhaft betreiben, auch wenn der Shop nach Eingriffen scheinbar wieder läuft.

Ist die Datenbank bereits ganz oder teilweise migriert und gibt es kein passendes Backup von vorher, ist der Weg nach vorn in aller Regel der richtige. Migrationen lassen sich zwar technisch zurückdrehen, aber nur mit dem Code der neueren Version und ohne Garantie, dass jede einzelne Änderung sauber umkehrbar ist.

Schritt 3: Dateien auf einen konsistenten Stand bringen

Spielen Sie das vollständige Paket der Zielversion ein. Achten Sie darauf, dass keine Altlasten einer anderen Version im Migrationsverzeichnis liegen bleiben. Im beschriebenen Fall des Rollbacks bestand die Lösung darin, zunächst die übrig gebliebenen Migrationsdateien zu entfernen, deren Nummer höher war als die letzte Zeile in tmigration. Damit verschwand der Fatal Error. Anschließend wurde der Shop vorwärts auf 5.7.2 aktualisiert und lief danach stabil.

Entfernen Sie Migrationsdateien nur, wenn Sie den Stand vorher wie oben beschrieben verglichen und gesichert haben. Ändern Sie keine Einträge in tmigration oder tversion von Hand, um den Shop zu „überreden“. Damit verschleiern Sie den Zustand, statt ihn zu beheben.

Schritt 4: Datenbank-Update vollständig ausführen

Melden Sie sich im Backend an und öffnen Sie das Datenbank-Update (/admin/dbupdater). Lassen Sie es bis zum Ende laufen. Bricht es ab, holen Sie die Meldung aus jtllogs bzw. dem PHP-Fehlerprotokoll, statt den Vorgang wiederholt neu zu starten. Danach prüfen Sie erneut tversion und die letzten Einträge in tmigration: Die Datenbankversion sollte jetzt zur eingespielten Dateiversion passen und es sollten keine offenen Migrationen mehr angezeigt werden.

Schritt 5: Shop testen

Leeren Sie den Cache im Backend, rufen Sie Startseite, Kategorie, Artikel und Warenkorb auf und führen Sie eine Testbestellung durch. Prüfen Sie danach Plugins und Template – gerade Child-Templates mit vollständig überschriebenen Dateien und ältere Plugins zeigen Fehler oft erst nach dem Update.

Fehlerbild auf einen Blick

So vermeiden Sie das Problem beim nächsten Update

• Staging zuerst: Testen Sie jedes Update auf einer Kopie des Shops mit aktuellen Daten, bevor Sie den Live-Shop anfassen.
• Dateien und Datenbank gemeinsam sichern: unmittelbar vor dem Update, mit eindeutigem Datum. Nur so ist ein echtes Zurück möglich.
• Plugin- und Template-Kompatibilität prüfen: Klären Sie vorab, ob alle Plugins und das Template die Zielversion unterstützen. Ein inkompatibles Plugin kann das Update verhindern oder danach Fehler auslösen.
• Update nicht halb liegen lassen: Nach dem Hochladen der Dateien das Datenbank-Update sofort ausführen und Ergebnis prüfen.
• Rollback nur vollständig: Wer zurück will, setzt Dateien und Datenbank gemeinsam auf denselben Sicherungsstand zurück. Die alte Version nur über die neuen Dateien zu kopieren, lässt Dateien der neueren Version liegen – genau daraus entstehen die beschriebenen Fehler.

Wenn Sie nicht weiterkommen

Bleibt der Shop trotz konsistenter Dateien und abgeschlossenem Datenbank-Update fehlerhaft, notieren Sie Dateiversion, Werte aus tversion, die letzten Einträge in tmigration und die Meldung aus dem Protokoll. Damit lässt sich der Fehler gezielt eingrenzen. Als zertifizierter JTL-Servicepartner unterstützt PC-Mixx Sie bei der Analyse und dabei, das Update sauber abzuschließen.

Häufige Fragen