Magento 2's Hidden Redirect Loop: The Case of Percent-Encoded URLs and Proxy Normalization

Magento 2's Hidden Redirect Loop: The Case of Percent-Encoded URLs and Proxy Normalization

As e-commerce migration experts at Shopping Mover, we constantly monitor the Magento ecosystem for critical insights that impact merchants and developers. A recent GitHub issue (#41616) highlights a subtle yet significant bug in Magento 2's URL rewrite functionality, particularly when dealing with percent-encoded characters and modern web infrastructure like reverse proxies or CDNs. This issue, identified by Fast White Cat, reveals a scenario leading to dreaded 'Too Many Redirects' errors, severely impacting user experience and SEO.

The Problem: A Loop of Misunderstanding Between Magento and Proxies

The core of the problem lies in how Magento 2 handles custom URL rewrites containing percent-encoded characters (e.g., %c5%82 for 'ł'). While RFC 3986 section 6.2.2.1 explicitly states that hex digits within percent-encoding are case-insensitive (meaning %c5%82 and %C5%82 are equivalent), Magento's internal logic was, until this fix, creating a conflict.

Here's the breakdown of the redirect loop:

• Scenario: A Magento store operates behind a reverse proxy or CDN (like Traefik) that normalizes percent-encoding by converting hex digits to uppercase (e.g., transforming %c5%82 to %C5%82).
• Admin Configuration: A custom URL rewrite is set up in Magento Admin with a request path like test-%c5%82.html.
• The Request: A user requests https:///test-%c5%82.html.
• Proxy Normalization: The proxy intercepts the request and, following its normalization rules, forwards https:///test-%C5%82.html to the Magento web server.
• Magento's Internal Conflict: Magento's url_rewrite lookup correctly identifies the configured rewrite because the database collation for request_path is case-insensitive. However, subsequent internal validation in Magento\UrlRewrite\Model\Storage\DbStorage::prepareUrlRewrite() and extractMostRelevantUrlRewrite() performs a strict comparison between the requested path (%C5%82) and the stored path (%c5%82). Since the hex cases differ, Magento incorrectly perceives them as distinct URLs.
• The Redirect Loop: Magento then issues a 301 redirect to the stored spelling (test-%c5%82.html). When this redirect goes back through the proxy, the proxy again normalizes it to test-%C5%82.html, sending it back to Magento, thus creating an infinite redirect loop that ultimately results in a 'ERR_TOO_MANY_REDIRECTS' error in the browser.

Impact and Severity

This issue was classified with a Severity S2, meaning it affects non-critical data or functionality but forces users to employ a workaround. For stores serving international audiences, relying on percent-encoded characters for special symbols in URLs, or those with complex SEO strategies, this bug can be a significant roadblock. It directly impacts user accessibility, search engine indexing, and overall site health.

The Solution: Aligning with Web Standards

The proposed fix, as indicated in the release note, addresses this discrepancy by ensuring that URL rewrites with percent-encoded characters correctly match requests regardless of the hex case used. This means Magento's internal comparison logic will be updated to be case-insensitive for the hex digits within percent-encoded segments, aligning with RFC 3986. This crucial update will prevent the unnecessary 301 redirects and resolve the redirect loops, ensuring that URLs are handled consistently across Magento and modern web infrastructure.

Why This Matters for Merchants and Developers

For merchants, this fix means greater reliability for internationalized URLs and custom SEO-friendly paths. It removes a hidden pitfall that could lead to broken links and a poor user experience, especially when migrating or integrating Magento with advanced proxy/CDN setups. For developers, it highlights the importance of deep dives into RFC compliance and how subtle differences in string comparison can lead to cascading issues. Understanding such nuances is critical for building robust, scalable, and globally accessible Magento solutions. This fix will streamline URL management and reduce the need for complex workarounds related to percent-encoded URLs.