Probleme nach dem TYPO3-Upgrade

Kurz: Die meisten Fehler nach einem TYPO3-Upgrade haben eine von wenigen Ursachen: eine veraltete Datenbankstruktur, nicht ausgeführte Upgrade-Wizards, inkompatible Extensions, eine unpassende PHP-Version oder alte Caches. Die genaue Ursache steht fast immer im Log – der erste Schritt ist deshalb, die Fehlermeldung sichtbar zu machen.

Erst die Fehlermeldung, dann die Lösung

Im Live-Betrieb zeigt TYPO3 bewusst keine Details, sondern eine weiße Seite oder „Oops, an error occurred!“. Die eigentliche Meldung finden Sie hier:

• Im TYPO3-Log: je nach Version und Installationsart unter var/log/ oder typo3temp/var/log/, in den Dateien typo3_*.log.
• Im Debug-Modus: im Modul Settings unter Configuration Presets → Debug settings. Nur auf einer Testumgebung einschalten, nie auf der Live-Seite – die Meldungen verraten Pfade und Konfiguration.
• Im Log des Webservers: wenn TYPO3 selbst gar nicht mehr startet, etwa bei einem PHP-Fehler, bevor das Framework geladen ist.

Die Module Settings, Maintenance und Upgrade liegen in TYPO3 9 bis 13 unter „Admin Tools“, ab TYPO3 14 unter „System“; in älteren Versionen stecken dieselben Werkzeuge im Install Tool. Die Bezeichnungen hier folgen dem englischen Backend.

Die häufigsten Fehlerbilder

Weiße Seite, Fehler 500 oder „Oops, an error occurred!“

Fast immer steckt ein PHP-Fehler dahinter. Typische Auslöser sind eine Extension, die mit der neuen TYPO3- oder PHP-Version nicht zurechtkommt, oder eigener Code, der eine Klasse oder Methode nutzt, die der Core entfernt hat. Die Meldung im Log nennt Datei und Zeile – und damit meist die Extension.

Die Lösung ist eine kompatible Version der Extension oder ein Ersatz. Zum Eingrenzen lässt sich eine Extension auf der Testumgebung auch vorübergehend deaktivieren. Tritt der Fehler erst nach einem PHP-Wechsel auf, prüfen Sie, ob Ihre TYPO3-Version die neue PHP-Version überhaupt unterstützt: Welche PHP-Version braucht TYPO3?

Datenbankfehler: „Table … doesn’t exist“ oder „Unknown column“

Die neue TYPO3-Version erwartet Tabellen oder Felder, die es in der Datenbank noch nicht gibt. Im Modul Maintenance vergleicht Analyze database structure die Datenbank mit dem Soll-Zustand und legt fehlende Tabellen und Felder an. Danach folgen die Upgrade-Wizards im Modul Upgrade: Sie migrieren Daten, deren Aufbau sich zwischen den Versionen geändert hat.

Vorsicht bei den Löschvorschlägen der Strukturanalyse: TYPO3 entfernt nicht mehr benötigte Tabellen und Felder nicht sofort, sondern benennt sie mit dem Präfix zzz_deleted_ um. Endgültig löschen erst, wenn die Seite vollständig läuft und ein Backup existiert.

Inhalte fehlen oder die Seite sieht anders aus

Das Frontend baut auf TypoScript, Fluid-Templates und Inhaltselementen auf – und jede LTS-Version entfernt Funktionen, die vorher als veraltet markiert waren. Zwei bekannte Beispiele:

• Die alten TypoScript-Bedingungen wie [hostname = …] oder [applicationContext = …] gibt es seit TYPO3 10 nicht mehr. Seit TYPO3 9.4 schreiben sich Bedingungen in der Symfony Expression Language.
• Die Erweiterung css_styled_content ist seit TYPO3 9 nicht mehr Teil des Core. Ihr Nachfolger ist fluid_styled_content.

Welche Änderungen eine Version mitbringt, zeigt die Upgrade-Dokumentation im Modul Upgrade, gegliedert nach Breaking Changes und Deprecations. Der Extension Scanner im selben Modul durchsucht eigene Extensions nach Code, der entfernte Funktionen nutzt. Am meisten Arbeit spart das Deprecation-Log auf der alten Version: Was dort auftaucht, fällt mit der nächsten Version weg.

Bilder fehlen nach dem Upgrade von TYPO3 4.5

Mit TYPO3 6.0 kam das File Abstraction Layer (FAL): Dateien und ihre Verknüpfungen liegen seitdem in eigenen Tabellen. Die Upgrade-Wizards auf dem Weg zu 6.2 migrieren die alten Bildverknüpfungen. Wurden sie übersprungen oder sind sie abgebrochen, fehlen Bilder im Frontend, obwohl die Dateien noch auf dem Server liegen.

Am saubersten ist ein Neuanfang vom Backup vor dem Schritt auf 6.2, diesmal mit vollständig durchlaufenen Wizards – ein Grund mehr, jede LTS-Version einzeln zu durchlaufen.

URLs haben sich geändert (Upgrade von 8.7 oder älter)

Bis TYPO3 8.7 erzeugte meist die Extension RealURL die sprechenden URLs. Ab TYPO3 9 übernimmt der Core das Routing selbst, gesteuert über die Site-Konfiguration (Modul Sites) und die URL-Segmente („Slugs“) der Seiten; RealURL gibt es für diese Versionen nicht. Ohne Nacharbeit ändern sich dabei Adressen – für Suchmaschinen sind das neue Seiten, und alte Links laufen ins Leere.

Legen Sie deshalb die Site-Konfiguration an, gleichen Sie die Slugs mit den bisherigen URLs ab und richten Sie für jede geänderte Adresse eine Weiterleitung ein. Dafür bringt TYPO3 seit Version 9 das Modul Redirects mit.

Änderungen sind nicht sichtbar

TYPO3 speichert Seiten, Konfiguration und kompilierten Code zwischen, PHP zusätzlich den Bytecode (OPcache). Nach einem Upgrade leert Flush TYPO3 and PHP cache im Modul Maintenance beides. Sieht das Backend danach noch fehlerhaft aus, liegt es oft am Browser-Cache – ein harter Reload hilft.

So vermeiden Sie die meisten Probleme

1. Nie auf der Live-Seite upgraden, sondern auf einer Kopie mit derselben PHP- und Datenbankversion.
2. Jede LTS-Version dazwischen einzeln durchlaufen und nach jedem Schritt Datenbankstruktur und Upgrade-Wizards abschließen. Welche Zwischenschritte Ihr Upgrade braucht, zeigt die Übersicht der Upgrade-Pfade.
3. Vorher alle Extensions prüfen: Gibt es kompatible Versionen, und nutzt eigener Code entfernte Funktionen? Für den Schritt von 12 auf 13 zeigt die Seite Upgrade von TYPO3 12 auf 13, welche Fälle dabei vorkommen.
4. PHP getrennt von TYPO3 wechseln – welche PHP-Version zu welchem Schritt passt.
5. Unmittelbar vor der Umstellung ein Backup von Dateien und Datenbank anlegen und wissen, wie Sie zurückkommen.

Wenn die Live-Seite nicht mehr läuft

Stellen Sie zuerst den letzten funktionierenden Stand wieder her – Dateien und Datenbank gemeinsam, aus demselben Backup. Die Fehlersuche gehört auf eine Kopie, nicht auf die Seite, die Ihre Besucher sehen.

Hilfe von außen lohnt sich, wenn kein sauberes Backup da ist, wenn mehrere Versionen auf einmal übersprungen wurden oder wenn eigene Extensions betroffen sind, die niemand mehr genau kennt. Solche Fälle übernimmt unser TYPO3 Support – oder schreiben Sie uns über das Formular unten.

Stand: 24.9.2026 · Quellen: TYPO3 Explained: Major upgrade, TYPO3 Core Changelog