TYPO3 13 Upgrade mit Flux 11: Warum alle Partials eine Configuration-Section brauchen

Einleitung: Das Problem beim Upgrade

Beim Upgrade bestehender TYPO3-Projekte von TYPO3 11/12 auf TYPO3 13 treten in Kombination mit FluidTYPO3/Flux 11 Fehler auf, die besonders unangenehm sind: Sie passieren sehr früh im Bootstrap und blockieren sowohl Backend als auch Frontend vollständig. In der Praxis bedeutet das: Kein Login ins Backend, keine Ausgabe im Frontend, und selbst ein simples Cache-Flush über die CLI scheitert.

Das Problem betrifft vor allem Projekte, die Flux-Konfigurationen modularisiert haben, indem sie Konfigurations-Templates in Partials ausgelagert und diese über Sections eingebunden haben. Was in älteren Flux-/Fluid-Konstellationen problemlos funktionierte, wird unter Flux 11 (mit TYPO3Fluid 4.x) zu einem harten Breaking-Point.

Fehlermeldung und warum sie so wenig Information liefert

Typisch ist ein Fatal Error während des Content-Type-Bootstraps. Der Fehler tritt so früh auf, dass TYPO3 weder Backend noch Frontend initialisieren kann. Besonders frustrierend: Auch der Versuch, den Cache zu leeren, scheitert, weil genau derselbe Bootstrap-Pfad ausgeführt wird.

In vielen Setups sieht man beim Aufruf von Backend/Frontend nur eine generische Exception-Ausgabe. Auf der CLI (z. B. bei cache:flush) wird die Exception häufig durch das Symfony Console Framework in einer Form ausgegeben, die zwar den Exception-Typ zeigt, aber keinen vollständigen Stack Trace und vor allem keinen Hinweis auf die betroffene Template-Datei liefert. Genau das ist der Kern des Problems: Du weißt, dass irgendwo eine Section fehlt – aber nicht, in welchem Partial oder Template.

Das führt in der Praxis zu einem „Blackout“-Moment: Das System ist tot, Logs sind nicht aussagekräftig genug, und du brauchst eine Strategie, um die konkrete Datei zu identifizieren.

Technische Ursache (Flux-Quellcode-Analyse)

Die Ursache liegt in der Art, wie Flux beim Bootstrap Konfiguration aus Fluid-Templates extrahiert. Zentral ist dabei die Methode AbstractProvider::extractConfiguration(). Dort ruft Flux (vereinfacht dargestellt) Folgendes auf:

$configurationSectionName = 'Configuration';
$configuration = $view->renderSection('Configuration', $viewVariables, false);

Der entscheidende Punkt ist der dritte Parameter von renderSection(): false. In TYPO3Fluid bedeutet das: Wenn die Section nicht existiert, soll eine Exception geworfen werden (also nicht „still“ fehlschlagen). Und weil $configurationSectionName = 'Configuration' in AbstractProvider seit jeher als Default fest verdrahtet ist (historisch u. a. um eine klare Konvention zu erzwingen), erwartet Flux beim Extrahieren der Konfiguration immer eine Section mit exakt diesem Namen.

Warum ist das plötzlich ein Problem, wenn es „schon immer“ so war?

Was früher funktionierte (Flux < 11 / ältere Fluid-Kontexte)

In älteren Flux-Versionen war es in vielen Projekten üblich, die Konfiguration in einer Section des Haupt-Templates zu definieren und darin Partials zu rendern, etwa so:

<f:section name="Configuration">
  <f:render partial="Configuration/Tracking" section="MultifunctionSheetTracking" />
</f:section>

Das Partial konnte dann eine eigene Section mit einem beliebigen Namen enthalten, z. B. MultifunctionSheetTracking oder newsletterSubscription. In der Praxis war der Section-Name im Partial häufig „frei gewählt“ und passte zum Zweck des Partials. Entscheidend: Das Rendering fand oft in einem Kontext statt, in dem Flux die Konfiguration aus dem Haupt-Template extrahierte und die Partials „im selben Rendering-Kontext“ liefen. Dadurch war es weniger relevant, wie die äußerste Section im Partial hieß – solange das Haupt-Template eine Configuration-Section hatte und die Konfiguration am Ende zusammenkam.

Was sich mit Flux 11 / TYPO3Fluid 4.x ändert

Mit Flux 11 (und dem Rendering-Verhalten von TYPO3Fluid 4.x) wird jedes Partial in einem eigenständigen Rendering-Kontext gerendert. Das ist ein wichtiger Unterschied: Flux versucht beim Content-Type-Bootstrap nicht nur das Haupt-Template zu analysieren, sondern kann in bestimmten Pfaden auch Partials als eigenständige Einheiten betrachten, insbesondere wenn sie als Konfigurationsquellen dienen oder durch Provider/Builder-Logik iteriert werden.

Die Folge: Flux ruft beim Bootstrap auf einem Partial ebenfalls renderSection('Configuration', ..., false) auf. Wenn das Partial aber keine Section namens Configuration besitzt, fliegt eine Exception – und weil das im Bootstrap passiert, ist das System komplett blockiert.

Genau hier entsteht der typische Fehler: Ein Partial enthält nur eine Section wie MultifunctionSheetTracking oder newsletterSubscription, aber keine Configuration-Section. Früher war das „okay“, weil das Partial nicht als eigenständige Konfigurationsquelle behandelt wurde. Jetzt wird es das – und Flux ist strikt.

Debugging-Strategie, um das betroffene Template zu finden

Wenn du Glück hast, findest du in den Logs (z. B. var/log) einen Hinweis auf den zuletzt gerenderten View. Häufig ist das aber nicht der Fall. Und auf der CLI fehlt dir oft der vollständige Stack Trace. Deshalb ist ein pragmatischer Ansatz sinnvoll: ein temporärer Patch, der dir die gerade verarbeitete Template-Datei ausgibt, bevor die Exception „verschluckt“ oder verkürzt ausgegeben wird.

Ein bewährter Ort dafür ist ContentTypeBuilder.php (in Flux), weil dort typischerweise die Content-Types gebaut und Templates/Partials iteriert werden. Ziel des Patches: Sobald Flux ein Template/Partial verarbeitet, loggst du den Dateipfad (oder wirfst eine Exception mit dem Pfad), um die problematische Datei zu identifizieren.

Ein minimal-invasiver Patch kann z. B. so aussehen (Prinzip, nicht 1:1 als Upstream-Code zu verstehen):

// TEMP PATCH: before rendering configuration
// $templatePathOrIdentifier contains the currently processed template/partial
throw new \RuntimeException('Flux debug: processing template ' . $templatePathOrIdentifier);

Vorgehen in der Praxis:

• Patch einbauen und den Bootstrap erneut auslösen (Backend-Aufruf oder CLI).
• Exception-Ausgabe ablesen: Du bekommst nun den Pfad/Identifier der Datei, die Flux gerade verarbeitet.
• Patch verfeinern: Statt sofort zu werfen, kannst du zuerst loggen und erst beim nächsten Schritt werfen – je nachdem, wie viele Dateien iteriert werden.
• Patch wieder entfernen, sobald du die betroffenen Partials/Templates identifiziert hast.

Caveat: Wenn Flux sehr viele Templates scannt, kann ein „throw“ zu früh sein. Dann ist Logging besser (z. B. in error_log). Wenn du aber wegen des Bootstrap-Fatal-Errors gar nicht erst in eine stabile Umgebung kommst, ist „hart abbrechen mit Pfad“ oft der schnellste Weg.

Die Lösung: Section-Namen vereinheitlichen

Die eigentliche Lösung ist simpel, aber konsequent: Alle Flux-Konfigurations-Partials müssen als äußerste Section eine Section namens Configuration besitzen. Das bedeutet:

• Partials, die bisher z. B. <f:section name="MultifunctionSheetTracking"> hatten, müssen auf <f:section name="Configuration"> umgestellt werden.
• Alle Templates, die diese Partials mit dem alten Section-Namen einbinden, müssen ebenfalls angepasst werden (weil sie sonst eine nicht mehr existierende Section rendern).

Vorher (problematisch unter Flux 11):

<!-- Partial: Configuration/Tracking.html -->
<f:section name="MultifunctionSheetTracking">
  ... Flux-Konfiguration ...
</f:section>

Und im Haupt-Template:

<f:section name="Configuration">
  <f:render partial="Configuration/Tracking" section="MultifunctionSheetTracking" />
</f:section>

Nachher (kompatibel):

<!-- Partial: Configuration/Tracking.html -->
<f:section name="Configuration">
  ... Flux-Konfiguration ...
</f:section>

Und im Haupt-Template:

<f:section name="Configuration">
  <f:render partial="Configuration/Tracking" section="Configuration" />
</f:section>

Wichtig: Wenn du Partials bisher bewusst mit unterschiedlichen Section-Namen versehen hast, um mehrere Konfigurationsvarianten in einer Datei zu kapseln, musst du das refactoren. Unter Flux 11 ist es deutlich robuster, pro Partial genau eine Konfigurations-Section Configuration vorzuhalten und Varianten über Parameter/Variablen zu steuern (oder separate Partials zu verwenden).

Bash-Snippet zum automatischen Fixen

In größeren Projekten willst du das nicht manuell in 30–200 Dateien anfassen. Du kannst die Umbenennung in vielen Fällen automatisieren. Trotzdem gilt: Bitte vorher committen oder einen Branch erstellen, denn ein blindes Suchen/Ersetzen kann auch Stellen treffen, die nicht Flux-Konfiguration sind.

1) Zuerst: Dateien finden, die verdächtige Section-Namen enthalten (Beispiel: alles außer Configuration):

grep -RIn --include='*.html' '<f:section name="[^"]*">' Packages/Extensions

2) Häufiger Quick-Fix: Ersetze in Konfigurations-Partial-Verzeichnissen die äußere Section auf Configuration. Wenn deine Konfigurations-Partials z. B. in Resources/Private/Partials/Configuration liegen:

find Packages/Extensions -path '*Resources/Private/Partials/Configuration/*.html' -print0 | xargs -0 sed -i 's/<f:section name="[A-Za-z0-9_]*">/<f:section name="Configuration">/g'

3) Danach musst du die Render-Aufrufe anpassen, die noch auf alte Section-Namen zeigen. Wenn du vorher z. B. section="MultifunctionSheetTracking" gerendert hast, musst du das auf section="Configuration" ändern. Für einen ersten Sweep (Achtung: nur sinnvoll, wenn du sicher bist, dass es sich um Flux-Konfigurations-Renderings handelt):

grep -RIn --include='*.html' 'partial="Configuration/' Packages/Extensions

Dann gezielt ersetzen (Beispiel für einen konkreten alten Namen):

find Packages/Extensions -name '*.html' -print0 | xargs -0 sed -i 's/section="MultifunctionSheetTracking"/section="Configuration"/g'

Realistische Caveats:

• sed -i verhält sich je nach OS unterschiedlich (GNU vs. BSD/macOS). Auf macOS brauchst du oft sed -i ''. Passe das an deine Umgebung an.
• Wenn du in einem Partial mehrere Sections hast, ist ein globales Replace gefährlich. Dann solltest du gezielt nur die äußerste Section ändern oder das Partial manuell refactoren.
• Nach dem Fix unbedingt alle betroffenen Content-Types einmal durchtesten (Backend: neues Element anlegen, Element bearbeiten, Frontend-Rendering prüfen).

Fazit und Empfehlung

Beim Upgrade auf TYPO3 13 mit Flux 11 kann ein scheinbar harmloses Pattern aus älteren Projekten – Konfigurations-Partials mit individuellen Section-Namen – zu einem vollständigen Systemstillstand führen. Der Kern ist technisch nachvollziehbar: Flux erwartet beim Extrahieren der Konfiguration strikt eine Section namens Configuration und wirft (durch renderSection(..., false)) eine Exception, wenn sie fehlt. Durch das veränderte Rendering-Verhalten in TYPO3Fluid 4.x werden Partials häufiger als eigenständige Einheiten gerendert, wodurch die fehlende Section plötzlich fatal wird.

Empfehlung für Upgrade-Projekte:

• Behandle jede Flux-Konfigurationsdatei (auch Partials) so, als würde Flux sie direkt bootstrappen: immer eine Configuration-Section.
• Nutze einen temporären Debug-Patch, wenn die Exception-Ausgabe nicht verrät, welche Datei betroffen ist.
• Automatisiere die Umstellung per Suche/Ersetzen, aber nur mit klarer Eingrenzung und sauberem Review.

Zusätzlicher Hinweis aus der Praxis: Es gibt derzeit keine wirklich klare offizielle Dokumentation, die diese Verhaltensänderung explizit als Breaking Change beschreibt. Weder der Flux-11.0.0-Changelog noch die offizielle Doku machen das prominent. Umso wichtiger ist es, diese Konvention im Team festzuhalten und bei künftigen Flux-Templates konsequent einzuhalten.