Upgrade von TYPO3 12 auf 13: was in der Praxis bricht

Kurz: Beim Upgrade von TYPO3 12.4 auf 13.4 bricht selten der Core selbst. Die Arbeit steckt an drei Stellen: in Extensions, für die es keine Version für TYPO3 13 gibt; in TypoScript, das TYPO3 13 nicht mehr auswertet, ohne einen Fehler zu melden; und in Funktionen, die beim Testen gern vergessen werden – Formular-E-Mails, die Suche und die Vorschauen im Backend. Wer die Extensions vor dem Core-Wechsel klärt und danach genau diese Stellen prüft, erlebt kaum Überraschungen.

Jetzt auf 13 – oder gleich auf 14?

Der kostenlose Support für TYPO3 12.4 endete am 30.4.2026, Sicherheitsupdates gibt es seitdem nur noch über das kostenpflichtige ELTS. TYPO3 13.4 wird bis zum 31.12.2027 gepflegt, TYPO3 14.3 bis zum 30.6.2029. Wie die Support-Phasen aufgebaut sind und wann ELTS eine Brücke sein kann, steht auf der Seite Wie lange bekommt TYPO3 Sicherheitsupdates?

Der direkte Sprung von 12 auf 14 klingt verlockend, verdoppelt aber die Breaking Changes in einem Schritt – und viele Extensions von Drittanbietern hatten bei unseren Upgrades noch keine Version für TYPO3 14. Wir gehen deshalb zuerst auf 13.4 und planen den Schritt auf 14 getrennt. Die Arbeit an 13 ist für 14 ohnehin Voraussetzung. Die Eckdaten dieses Schritts zeigt die Seite TYPO3 12.4 auf 13.4, Sprünge von älteren Versionen die Übersicht der Upgrade-Pfade.

Vor dem Core-Wechsel

1. Voraussetzungen prüfen. TYPO3 13.4 läuft mit PHP 8.2 bis 8.5 und braucht mindestens MariaDB 10.4.3 oder MySQL 8.0.17. Läuft Ihre Installation schon auf PHP 8.2 oder neuer, muss PHP für das Upgrade nicht wechseln – welche PHP-Version zu welcher TYPO3-Version passt. Die Datenbankversion auf der Live-Umgebung prüfen, nicht nur lokal.
2. Alle Upgrade-Wizards von 12 abschließen. Die Wizards von TYPO3 13 setzen eine vollständig migrierte Datenbank voraus. vendor/bin/typo3 upgrade:list zeigt, was noch offen ist.
3. Das Deprecation-Log einschalten. Was TYPO3 12 als veraltet meldet, fehlt in 13. In vielen Installationen ist das Log abgeschaltet – für das Upgrade einschalten, vor dem Go-live wieder aus.
4. Die Werkzeuge auf 13 ausrichten und ihre Berichte als Arbeitsliste nutzen: TYPO3 Rector für PHP und TCA (Regelsatz UP_TO_TYPO3_13), Fractor für TypoScript, FlexForms und XML, dazu der Extension Scanner oder typo3scan mit Ziel 13. Alle drei zuerst nur als Probelauf.
5. Jede Extension einordnen – das ist der größte Posten.

Extensions: hier steckt die meiste Arbeit

Zwei Kniffe verkleinern den eigentlichen Sprung. Erstens: Extensions, die es in einer Version für 12 und 13 gibt, schon auf 12 aktualisieren – dann ändert sich beim Core-Wechsel weniger gleichzeitig. Zweitens: Wo eine Version schon 12 bis 14 abdeckt, diese nehmen, etwa plan2net/webp 14. Das erleichtert den nächsten Schritt.

gridelements: auf 12 ablösen, nicht auf 13

gridelements hatte zum Zeitpunkt unserer Upgrades keine Version für TYPO3 13. Der übliche Nachfolger b13/container unterstützt in Version 3 TYPO3 11.5, 12.4 und 13.4 – die Migration lässt sich deshalb vor dem Core-Wechsel auf 12 erledigen:

1. Die Container-Typen registrieren und die Templates portieren, zusätzlich zu gridelements.
2. Die Inhalte migrieren, etwa mit der Extension gridtocontainer. Sie schreibt Inhaltstyp, Eltern-Element und Spalten um; die Container-Typen legt sie nicht selbst an.
3. Das Frontend vergleichen, am besten mit visuellen Regressionstests, dann gridelements entfernen.

Die Migration ändert nur die Datenbank und lässt sich nicht beliebig wiederholen. Sie muss auf jeder Umgebung einzeln laufen, mit Backup und ohne dass gleichzeitig jemand Inhalte bearbeitet. Zählen Sie vorher und nachher: In unserem Fall mussten rund 900 Kindelemente aus drei Layouts wieder genau in ihren Spalten landen. Und prüfen Sie gemeinsame Layout-Templates auf Bedingungen, die gridelements-Felder abfragen – bei uns bekamen Container-Kinder dadurch einen doppelten Wrapper.

Was TYPO3 13 still ignoriert

Die unangenehmsten Fehler melden sich nicht. Die Seite läuft, nur ein Detail fehlt:

• Bedingungen auf twoLetterIsoCode. Eine Bedingung wie [siteLanguage("twoLetterIsoCode") == "en"] ist in TYPO3 13 nie mehr wahr. Es gibt keinen Fehler, sie greift einfach nicht – bei uns fehlte dadurch das englische Logo. Prüfen Sie stattdessen zum Beispiel die languageId.
• TSFE:tmpl in TypoScript. Den TemplateService gibt es in TYPO3 13 nicht mehr. Ausdrücke wie data = TSFE:tmpl|setup|sitetitle liefern deshalb nichts – je nach Fehlereinstellung ein leeres Feld, etwa im og:site_name, oder einen Abbruch mit Fehler 500. Ersatz: den Titel als websiteTitle in der Site-Konfiguration pflegen und mit data = site:websiteTitle auslesen.
• Einstellungen, die es nicht mehr gibt, etwa GFX/processor_allowTemporaryMasksAsPng oder der Cache imagesizes. Sie schaden nicht, stiften aber Verwirrung. Beim Upgrade gleich aus config/system/settings.php entfernen.

Umgekehrt meldet eine Testumgebung mit Debug-Einstellungen mehr als die Live-Seite: Dort macht TYPO3 auch Deprecations zu Fehlern. In einem Projekt brachte eine Crawler-Version so jede Seite zum Absturz, weil sie eine Eigenschaft beschrieb, die es in TYPO3 13 nicht mehr gibt – im Live-Betrieb wäre das nur im Log aufgefallen. Testen Sie mit Debug-Einstellungen und beheben Sie, was dabei auftaucht, aber übernehmen Sie diese Einstellungen nicht live.

Nach dem Wechsel: die Stellen, die gern vergessen werden

Formulare: ohne Textvorlage Fehler 500

Der E-Mail-Finisher von EXT:form rendert in TYPO3 13 immer auch eine Textfassung der Mail, selbst wenn Sie HTML-Mails verschicken; die alte Option format: html wird ignoriert. Gibt es in eigenen Mail-Templates nur .html-Dateien, endet jedes Absenden mit Fehler 500 (InvalidTemplateResourceException). Die Lösung ist eine .txt-Vorlage zu jedem Mail-Template. Testen Sie jedes Formular mit echtem Versand und fangen Sie die Mails in einem Testpostfach ab, zum Beispiel mit Mailpit in DDEV.

Suche: alte Template-Overrides

Ein angepasstes Such-Template von EXT:indexed_search nutzte ViewHelpers für die Seitennavigation, die TYPO3 13 entfernt hat (is:pageBrowsingResults, is:pageBrowsing). Ergebnis: Fehler 500 auf der Suchseite. TYPO3 13 arbeitet mit einem Pagination-Objekt und dem Partial Pagination aus dem Core; das eigene Template muss daran angepasst werden. Bei EXT:ke_search war es nach dem Update umgekehrt: Ein veraltetes Override brach die Seitennavigation, das Original der Extension funktionierte.

Die Regel dahinter: Jedes Override eines Extension-Templates friert den Stand einer alten Version ein. Listen Sie vor dem Upgrade alle Overrides auf und vergleichen Sie sie mit den Originalen der neuen Version. Und wenn EXT:crawler den Suchindex füllt, während die Indexierung beim normalen Seitenaufruf abgeschaltet ist: In TYPO3 13 bleibt der Index leer, bis ein Event-Listener für das EnableIndexingEvent die Indexierung für Crawler-Anfragen wieder einschaltet.

Backend: Vorschauen eigener Inhaltselemente

Eigene Vorschauen im Seitenmodul bauten oft auf StandaloneView auf, das in TYPO3 13 als veraltet gilt; der Ersatz ist das ViewFactoryInterface. Bei uns kamen zwei Änderungen hinzu, die erst beim Öffnen des Seitenmoduls auffielen: FormDataCompiler::compile() erwartet die Gruppe jetzt als zweites Argument, und die Eingabedaten brauchen den aktuellen Request. Testen Sie das Backend deshalb genauso gründlich wie das Frontend.

Wer Content Blocks nutzt, hebt sie von 0.7 auf 1.x. Der Migrations-Wizard benennt dabei Ordner um, unter anderem Assets in assets. Auf macOS unterscheidet das Dateisystem Groß- und Kleinschreibung meist nicht – diese Umbenennung kommt dann nicht sauber im Git an. Committen Sie sie von einem System, das Groß- und Kleinschreibung unterscheidet.

Datenbank: colPos und alte Spalten

• In TYPO3 13 ist tt_content.colPos eine Ganzzahl ohne Vorzeichen. Datensätze mit negativem colPos blockieren die Änderung der Tabelle – in unserem Fall 375 gelöschte Elemente mit -1. Prüfen Sie vor der Strukturanalyse mit SELECT uid, deleted FROM tt_content WHERE colPos < 0; und korrigieren Sie die Treffer nach einem Backup.
• Alte Spalten entfernter Funktionen können Schreibzugriffe blockieren. Die Spalte metaphonedata der Suche (die Metaphone-Suche gibt es seit TYPO3 13.0 nicht mehr) hat keinen Standardwert; unter dem strikten SQL-Modus neuerer MariaDB-Versionen scheiterte deshalb jedes Einfügen, und der Suchindex blieb leer. Die Löschvorschläge der Strukturanalyse beheben das – zweimal ausgeführt, weil TYPO3 beim ersten Mal nur mit zzz_deleted_ umbenennt (mehr dazu bei den Problemen nach dem Upgrade).

Rector und Fractor: viel Arbeit, nicht alles

In unseren Upgrades haben die beiden Werkzeuge einen großen Teil der Routinearbeit erledigt: TCA-Felder wie renderType: inputLink auf type: link umgestellt, Auswahllisten auf die neue Schreibweise gebracht, Icons in Configuration/Icons.php und PageTSconfig in die automatisch geladene Configuration/page.tsconfig verschoben, den TCEforms-Wrapper aus FlexForms entfernt und Konstanten wie File::FILETYPE_* durch die neue Enum ersetzt.

Von Hand blieb, was echten Umbau braucht: StandaloneView auf die ViewFactory umstellen und <INCLUDE_TYPOSCRIPT> auf @import – Rector legt zwar die neue page.tsconfig an, die alten Includes darin bleiben aber stehen. Generierter Code, etwa aus EXT:mask, bekommt die Änderungen nur, bis er neu generiert wird.

Und nicht alles, was auf einer Liste steht, ist dringend. f:cObject und das Argument parseFuncTSPath von f:format.html sind in 13.4 nicht als veraltet markiert, auch wenn manche Übersichten das nahelegen. Maßgeblich ist der installierte Core.

Was bis zum Schritt auf 14 warten kann

Einiges funktioniert in 13.4 noch und lässt sich zusammen mit dem Upgrade auf 14 erledigen. Das hält den Umfang klein:

• Site Sets. TypoScript-Includes über sys_template funktionieren in 13.4 weiter.
• renderStatic() in eigenen ViewHelpers – veraltet seit 13.3, funktioniert aber.
• PageRenderer-Hooks – in 13.4 noch vorhanden, in 14.0 entfernt.

Planen Sie diese Punkte für den nächsten Schritt fest ein; aufgeschoben heißt nicht erledigt.

Die Reihenfolge, die sich bewährt hat

1. Auf 12: Snapshot, Extensions mit Version für 12 und 13 vorziehen, gridelements ablösen, alle Wizards abschließen.
2. Core-Sprung: alle typo3/cms-*-Pakete gemeinsam auf ^13.4 (composer update -W), Extensions mitziehen, Datenbankstruktur aktualisieren, bis Frontend und Backend wieder starten.
3. Rector und Fractor anwenden und das Ergebnis durchsehen.
4. Verbleibende Deprecations von Hand beheben.
5. Wizards und vollständiger Test: jede Sprache, Formulare mit echtem Versand, Suche und Indexierung, Backend-Vorschauen, Fehlerseiten, Content-Security-Policy.
6. Dokumentieren und markieren (Git-Tag), dann Staging, dann Live.

Nach jedem Schritt prüfen, bevor der nächste beginnt – dann ist klar, welcher Schritt einen Fehler verursacht hat.

PHP getrennt von TYPO3 wechseln. Reicht Ihre PHP-Version für TYPO3 13.4 noch nicht, heben Sie PHP zuerst an – auf eine Version, die 12.4 und 13.4 beide unterstützen – und aktualisieren erst dann TYPO3 (welche PHP-Version zu welchem Schritt passt). Vorsicht beim PHP-Wechsel mit composer update: In einem Projekt wollte Composer unter PHP 8.4 einzelne Symfony-Komponenten auf Version 8 heben, während der Core bei Symfony 7 blieb. Wer nur die PHP-Version wechseln will, ändert config.platform.php und aktualisiert mit composer update --lock nur die Prüfsumme der Lock-Datei.

Wenn Sie das Upgrade nicht selbst machen wollen

Wie viel Arbeit ein Upgrade auf 13 macht, entscheidet sich fast immer an den Extensions und am eigenen Code. Eine Bestandsaufnahme vorab zeigt, wo sie steckt. Das übernimmt unser TYPO3 Support – oder schreiben Sie uns über das Formular unten.

Stand: 24.9.2026 · Quellen: TYPO3 Changelog 13, TYPO3 Rector, Fractor, b13/container, gridtocontainer