Fixing TYPO3 RealURL Rules That Fail on Selected Parameters

A TYPO3 site can appear perfectly healthy until a visitor adds one query parameter to a URL. The page may return a 404, lose its speaking URL, redirect to the homepage, or display the wrong language. These failures are often blamed on Apache or nginx, although the real cause sits in the RealURL configuration and its handling of dynamic values. Learn more about Trusted Casino American Roulette.

This is especially confusing when ordinary links work. A product page such as /shop/item-name may resolve correctly, while /shop/item-name?tx_shop_pi1[uid]=42 creates a duplicate path or bypasses the expected page configuration. The difference is usually how RealURL maps path segments, GET variables, and extension parameters.

Australian sites can expose this problem in several ways: a Sydney campaign may add UTM values, a Melbourne retailer may use inventory filters, or a .com.au site may switch between English and regional landing pages. Caches at the application, reverse-proxy, and CDN levels can make the result vary between visitors in Brisbane, Perth, and Adelaide.

The safest fix is to isolate the parameter, identify which RealURL rule owns it, and then change one part of the configuration at a time. A clean test matrix is more useful than repeatedly clearing caches and hoping the next request behaves differently.

Symptom	Likely cause	First place to inspect	Typical remedy
URL returns 404 only with a parameter	Parameter is treated as a path segment	fixedPostVars or postVarSets	Define the variable or exclude it
Query string disappears after redirect	RealURL is canonicalising an incomplete URL	enableAllUnicodeLetters, redirects, page path rules	Preserve or explicitly map the value
Wrong record appears	Variable is mapped to the wrong table or field	lookUpProperty and alias settings	Correct the lookup configuration
Links work until cache expiry	Cached generated URLs contain stale rules	TYPO3 and RealURL caches	Flush caches after configuration changes
Tracking values create duplicate URLs	Marketing parameters are being encoded	preVars and query-string handling	Ignore non-routing parameters

Find The Failing Parameter

Begin with the smallest reproducible example. Record the working URL, then add one parameter at a time. For example, compare /news/article-title with /news/article-title?utm_source=google, followed by a TYPO3 parameter such as ?tx_news_pi1[news]=123. This separates harmless campaign data from a value that RealURL is attempting to resolve.

Use the browser’s network panel and TYPO3’s error log rather than relying solely on the visible page. A 301 or 307 indicates redirect logic, a 404 points towards route resolution, and a successful 200 response with the wrong content suggests an incorrect lookup rule. Check the generated Location header as well; it often reveals which segment RealURL has misinterpreted.

A useful habit is to test the same address without a trailing slash, with URL-encoded characters, and with parameters in a different order. Australian marketing platforms frequently append tracking values automatically, so a page that works in local development may fail when a campaign link is distributed through Google Ads or an email newsletter.

Understand How RealURL Reads Parameters

Older RealURL configurations commonly divide variables into preVars, fixedPostVars, and postVarSets. PreVars influence the URL before the page path, fixedPostVars describe a predictable sequence after the page, and postVarSets handle nested extension values. A parameter placed in the wrong group can cause RealURL to search for a page or database record that does not exist.

The important distinction is whether a value belongs to routing or is merely supplementary data. A news UID used to identify a record may need a proper lookup rule. utm_campaign, gclid, or a filter that should remain in the query string generally should not become part of the speaking path. Treating every GET variable as route data is the common source of broken variants.

Parameter names also matter. TYPO3 extension variables often use bracket notation, such as tx_news_pi1[news], while custom code may read a flat value like product. A rule written for one form will not reliably match the other. Check the actual request generated by the extension, not the parameter name you expected to see.

Correct The Configuration Carefully

A simplified legacy configuration might look like this:

'postVarSets' => [
    '_DEFAULT' => [
        'article' => [
            [
                'GETvar' => 'tx_news_pi1[news]',
                'lookUpTable' => [
                    'table' => 'tx_news_domain_model_news',
                    'id_field' => 'uid',
                    'alias_field' => 'path_segment',
                    'useUniqueCache' => 1,
                ],
            ],
        ],
    ],
],

The exact syntax depends on the TYPO3 and RealURL versions in use, so treat this as a diagnostic pattern rather than a drop-in recipe. The table, extension namespace, and alias field must match the installed extension. If a site has migrated from news to another extension, an old lookup table can silently send valid IDs to the wrong record set.

For a parameter that should not influence routing, exclude it instead of inventing a fake path mapping. Many projects use a preVars rule or a custom GETvar configuration to preserve selected values. Keep the rule narrow: excluding every unknown parameter may stop errors, but it can also hide a genuine routing defect and leave duplicate URLs for search engines.

Test Cases Worth Keeping

Build a small test set before changing production configuration. Store the expected status code, canonical URL, page title, and selected record for every request. This makes it possible to tell whether a fix solved the original failure or merely changed the symptom.

Useful routing cases include:

• The clean speaking URL without any query string
• One valid extension parameter with a known record
• An unknown record ID or alias
• A URL containing utm_source and utm_campaign

Then test formatting and operational cases separately. Include encoded spaces, ampersands, duplicate parameters, a trailing slash, and both HTTP and HTTPS requests. If the site serves visitors in Sydney and Melbourne through different cache nodes, test after cache expiry or purge the relevant layers so an old redirect does not confuse the result.

Keep a copy of the original RealURL configuration and change only one rule per deployment. A short browser test is not enough; generated menu links, pagination, language switches, RSS feeds, and canonical tags can all reveal a faulty mapping that a direct page request misses.

Check Extension And Custom Code

RealURL may be behaving consistently while an extension produces an unexpected parameter. Inspect TypoScript, Fluid links, f:link.action calls, and any PHP code that appends arguments. A custom controller can add a variable that was never included in the original route design, particularly after a TYPO3 or PHP upgrade.

When the extension itself needs adjustment, an XCLASS can be safer than editing vendor files, provided the override is small and documented. The practical background in custom XCLASS work is useful when a generated argument must be normalised before RealURL sees it. The override should validate input and preserve the extension’s public behaviour rather than rewriting URL logic in several places.

Also compare the current TYPO3 routing approach with the version of RealURL installed. Modern TYPO3 releases increasingly use site configuration and route enhancers instead of the older RealURL extension. Copying a legacy localconf.php rule into a newer installation can produce confusing results because the request is being processed by a different routing layer.

Clear Redirects And Caches

After changing the configuration, clear TYPO3 caches and regenerate affected pages. If a reverse proxy, Varnish layer, or CDN is present, purge redirects as well as HTML responses. A cached 301 can survive longer than the page that created it, making a correct configuration appear broken.

Review .htaccess or nginx rules for broad parameter handling. A server rule that removes all query strings, forces a slash, or redirects HTTP before TYPO3 receives the request can conflict with RealURL. The same applies to security modules that reject square brackets or encoded characters in extension parameters.

Campaign and referral URLs deserve a separate check. When comparing redirect behaviour across several sites, notes such as these URL troubleshooting examples can help distinguish application routing from browser or server-level rewriting. Keep the comparison technical: the important evidence is the request, response code, and final location, not the visual appearance of the destination page.

Protect Canonical URLs And Search Signals

Once the broken parameter is handled, inspect the canonical link and sitemap output. A tracking parameter should usually lead to the same canonical page as the clean URL. A record-identifying parameter, by contrast, may need a unique speaking URL and a meaningful canonical target. Returning a 200 response for multiple accidental variants can create a duplicate-content problem.

Check language and domain handling too. A .com.au installation may use separate language prefixes or country-specific domains, while a campaign from a local supermarket or travel company adds several tracking values. Ensure the fix does not remove a legitimate locale parameter or redirect an Australian landing page to an unrelated default language.

Finally, document the reason for each exception. A brief comment explaining that gclid is ignored, while tx_news_pi1[news] is resolved through a lookup table, will save time during the next TYPO3 upgrade. It also helps distinguish intentional URL design from a workaround that was added under pressure.

A reliable fix should leave clean URLs stable, preserve harmless tracking parameters, resolve valid extension records, and reject invalid values predictably. Apply the configuration in a staging environment, verify the request matrix, then deploy with cache purges planned. That disciplined process turns a mysterious RealURL failure into a repeatable TYPO3 maintenance task.