cHash for TYPO3

Most “Page not found” errors in TYPO3 are cHash problems

An editor creates a news item with pagination, and the page works. A visitor clicks through to page 2 and gets “Page not found”. The developer checks the routing, the page configuration, the .htaccess file. Everything is correct. The problem runs deeper: TYPO3’s cHash mechanism did not expect the pagination parameter in the URL and refuses to deliver the page. A five-minute problem if you know where to look, a two-day problem if you don’t.

cHash (cache hash) is TYPO3’s mechanism for protecting the page cache. It calculates a hash from all URL parameters and compares it with the stored cache entry. If an unknown parameter shows up that TYPO3 does not expect, the page is not delivered. This protects against cache poisoning, but causes problems with almost every new extension or custom filter.

Typical use cases

Filters and faceted search in product catalogs. A product catalog with 6 filter criteria (category, price, color, material, availability, rating) generates URL parameters such as &tx_catalog[color]=red&tx_catalog[price]=100-200. Without a cHash configuration, TYPO3 returns “Page not found” for every filter combination. The cHash configuration has to know each of these parameters, either as “required” (it affects the cache key) or as “excluded” (it is ignored and not hashed).

Pagination in news and event lists. EXT:news and EXT:sf_event_mgt use their own URL parameters for page numbers (&tx_news_pi1[@widget_0][currentPage]=2). These parameters must be part of the cHash configuration so that page 2 gets its own cache entry. Without it, either page 1 is always served from the cache (cache pollution) or pagination fails with a 404.

Tracking parameters and UTM tags. Marketing campaigns append UTM parameters to URLs: ?utm_source=newsletter&utm_medium=email. Unless these parameters are excluded, every campaign link creates a new cache entry. On a website with 500 pages and 10 campaigns, you suddenly have 5,000 cache entries instead of 500, which puts load on the server and slows down cache warmup. UTM parameters belong on the exclude list.

Technical architecture

The cHash is calculated in TYPO3’s core class CacheHashCalculator. The algorithm takes all URL parameters, sorts them alphabetically, serializes them and calculates an MD5 hash. This hash is appended to the URL as the cHash parameter. When the page is requested, TYPO3 checks whether the cHash supplied matches the calculated one.

The configuration lives in $GLOBALS['TYPO3_CONF_VARS']['FE']['cacheHash'] and consists of four lists:

cachedParametersWhiteList: parameters that feed into the hash and create cache entries of their own. Typically plugin parameters (tx_news_pi1, tx_solr).

excludedParameters: parameters that are ignored entirely. Typically tracking parameters (utm_source, utm_medium, utm_campaign, utm_content, utm_term, gclid, fbclid).

requireCacheHashPresenceParameters: parameters that strictly require a cHash. If such a parameter appears in the URL without a cHash, TYPO3 returns a 404 error. This is the most restrictive mode.

excludedParametersIfEmpty: parameters that are ignored only when they are empty.

Since TYPO3 v12, the cHash configuration can also be managed through the site configuration (config.yaml), which makes administration easier in multi-site setups.

Common problems and solutions

“Page not found” after installing an extension. New extensions bring their own URL parameters. If these are missing from the cHash configuration, TYPO3 blocks the page. The fix: check the extension documentation (good extensions ship their cHash configuration in ext_localconf.php). If they don’t, add the parameters manually to cachedParametersWhiteList or excludedParameters. In the TYPO3 Install Tool, the cHash debug mode under “Presets” helps with the diagnosis.

Cache pollution from uncontrolled parameters. Bots and spam crawlers append random parameters to URLs. Without protection, every one of these requests creates a cache entry. The cache grows to millions of entries and the database slows down. The fix: set excludeAllEmptyParameters = true and add only explicitly known parameters to the whitelist. In addition, run the cache garbage collector at shorter intervals (default: 86,400 seconds, i.e. 24 hours).

cHash errors are hard to debug. TYPO3 only shows “Page not found”, not the reason. In production mode, no error message points to cHash. The fix: temporarily set $GLOBALS['TYPO3_CONF_VARS']['FE']['pageNotFoundOnCHashError'] = false in LocalConfiguration.php. TYPO3 then displays the page despite the cHash error and logs the error. Set the value back to true once the diagnosis is done.

Migration and version compatibility

cHash is core functionality, not an extension, and has existed since TYPO3 v4. Its configuration has changed across versions: in TYPO3 v8 and earlier it was controlled via TypoScript, from v9 via PHP arrays in LocalConfiguration, and from v12 additionally via the site configuration.

When migrating from TYPO3 v9/v10 to v12/v13, existing cHash configurations have to be reviewed. Extension parameter names may have changed (for example through changes to Extbase plugin namespaces). The safest approach: after the upgrade, systematically test every page that uses parameters (pagination, filters, search) and check the TYPO3 error log for cHash entries.

TYPO3 v13 tightens the cHash check further: unknown parameters lead to a 404 by default, and debug mode has to be enabled explicitly. On every TYPO3 upgrade project, Gosign reviews the cHash configuration as part of its quality assurance process.