cHash for TYPO3

Die meisten “Page not found”-Fehler in TYPO3 include cHash-Probleme

Ein Redakteur legt eine Nachricht mit Paginierung an, die Seite funktioniert. Ein Besucher klickt auf Seite 2, sieht “Page not found”. Der Entwickler prüft das Routing, die Seitenkonfiguration, die .htaccess. Alles korrekt. Das Problem sitzt tiefer: TYPO3s cHash-Mechanismus hat den URL-Parameter der Paginierung nicht erwartet und verweigert die Auslieferung. Ein 5-Minuten-Problem, wenn man weiß, wo man suchen muss, ein 2-Tage-Problem, wenn nicht.

cHash (Cache Hash) ist TYPO3s Mechanismus zur Sicherung des Seiten-Caches. Er berechnet einen Hash aus allen URL-Parametern und vergleicht ihn mit dem gespeicherten Cache-Eintrag. Wenn ein unbekannter Parameter auftaucht, den TYPO3 nicht erwartet, wird die Seite nicht ausgeliefert. Das schützt vor Cache-Poisoning, verursacht aber bei fast jeder neuen Extension oder jedem Custom-Filter Probleme.

Typical use cases

Filter- und Facettensuche in Produktkatalogen. Ein Produktkatalog mit 6 Filterkriterien (Kategorie, Preis, Farbe, Material, Verfügbarkeit, Bewertung) erzeugt URL-Parameter wie &tx_catalog[color]=red&tx_catalog[price]=100-200. Ohne cHash-Konfiguration zeigt TYPO3 bei jeder Filterkombination “Page not found”. Die cHash-Konfiguration muss jeden dieser Parameter kennen, entweder als “required” (beeinflusst den Cache-Key) oder als “excluded” (wird ignoriert und nicht gehasht).

Paginierung in News- und Event-Listen. EXT:news und EXT:sf_event_mgt nutzen eigene URL-Parameter für Seitenzahlen (&tx_news_pi1[@widget_0][currentPage]=2). Diese Parameter müssen in der cHash-Konfiguration stehen, damit Seite 2 einen eigenen Cache-Eintrag erhält. Fehlt die Konfiguration, wird entweder immer Seite 1 aus dem Cache geliefert (Cache-Pollution) oder die Paginierung schlägt mit 404 fehl.

Tracking-Parameter und UTM-Tags. Marketing-Kampagnen hängen UTM-Parameter an URLs: ?utm_source=newsletter&utm_medium=email. Ohne Ausschluss dieser Parameter erzeugt jeder Kampagnen-Link einen neuen Cache-Eintrag. Bei einer Website mit 500 Seiten und 10 Kampagnen entstehen statt 500 plötzlich 5.000 Cache-Einträge, die den Server belasten und den Cache-Warmup verlangsamen. UTM-Parameter gehören auf die Exclude-Liste.

Technical architecture

Die cHash-Berechnung findet in TYPO3s Core-Klasse CacheHashCalculator statt. Der Algorithmus nimmt alle URL-Parameter, sortiert sie alphabetisch, serialisiert sie und berechnet einen MD5-Hash. Dieser Hash wird als cHash-Parameter an die URL angehängt. Beim Seitenaufruf prüft TYPO3, ob der mitgelieferte cHash mit dem berechneten übereinstimmt.

Die Konfiguration erfolgt in $GLOBALS['TYPO3_CONF_VARS']['FE']['cacheHash'] mit vier Listen:

cachedParametersWhiteList: Parameter, die in den Hash einfließen und eigene Cache-Einträge erzeugen. Typisch: Plugin-Parameter (tx_news_pi1, tx_solr).

excludedParameters: Parameter, die komplett ignoriert werden. Typisch: Tracking-Parameter (utm_source, utm_medium, utm_campaign, utm_content, utm_term, gclid, fbclid).

requireCacheHashPresenceParameters: Parameter, die einen cHash zwingend erfordern. Wenn dieser Parameter ohne cHash in der URL steht, zeigt TYPO3 einen 404-Fehler. Das ist der restriktivste Modus.

excludedParametersIfEmpty: Parameter, die nur ignoriert werden, wenn sie leer sind.

Seit TYPO3 v12 lässt sich die cHash-Konfiguration auch über die Site Configuration (config.yaml) steuern, was die Verwaltung in Multi-Site-Setups vereinfacht.

Common problems and solutions

“Page not found” nach Extension-Installation. Neue Extensions bringen eigene URL-Parameter mit. Wenn diese nicht in der cHash-Konfiguration stehen, blockiert TYPO3 die Seite. Lösung: Die Extension-Dokumentation prüfen (gute Extensions liefern cHash-Konfiguration in ext_localconf.php mit). Falls nicht: die Parameter manuell in die cachedParametersWhiteList oder excludedParameters eintragen. Im TYPO3 Install Tool unter “Presets” bietet der cHash-Debug-Modus eine Hilfestellung.

Cache-Pollution durch unkontrollierte Parameter. Bots und Spam-Crawler hängen zufällige Parameter an URLs. Ohne Schutz erzeugt jeder dieser Aufrufe einen Cache-Eintrag. Der Cache wächst auf Millionen Einträge, die Datenbank wird langsam. Lösung: excludeAllEmptyParameters = true setzen und nur explizit bekannte Parameter in die WhiteList aufnehmen. Zusätzlich den Cache-Garbage-Collector auf kürzere Intervalle stellen (Standard: 86.400 Sekunden = 24 Stunden).

cHash-Fehler schwer zu debuggen. TYPO3 zeigt nur “Page not found”, nicht warum. Im Production-Modus gibt es keine Fehlermeldung, die auf cHash hinweist. Lösung: In LocalConfiguration.php temporär $GLOBALS['TYPO3_CONF_VARS']['FE']['pageNotFoundOnCHashError'] = false setzen. Dann zeigt TYPO3 die Seite trotz cHash-Fehler an und loggt den Fehler. Nach der Diagnose wieder auf true setzen.

Migration and version compatibility

cHash ist Core-Funktionalität, keine Extension, und existiert seit TYPO3 v4. Die Konfiguration hat sich über die Versionen verändert: In TYPO3 v8 und früher wurde sie über TypoScript gesteuert, ab v9 über PHP-Arrays in der LocalConfiguration, ab v12 zusätzlich über die Site Configuration.

Bei der Migration von TYPO3 v9/v10 auf v12/v13 müssen bestehende cHash-Konfigurationen geprüft werden. Die Parameter-Namen der Extensions können sich geändert haben (z.B. Extbase-Plugin-Namespace-Änderungen). Der sicherste Weg: Nach dem Upgrade alle Seiten mit Parametern systematisch testen (Paginierung, Filter, Suche) und das TYPO3 Error Log auf cHash-Einträge prüfen.

TYPO3 v13 verschärft die cHash-Prüfung weiter: Unbekannte Parameter führen standardmäßig zu einem 404, der Debug-Modus muss explizit aktiviert werden. Gosign prüft bei jedem TYPO3-Upgrade-Projekt die cHash-Konfiguration als Teil des Qualitätssicherungs-Prozesses.