X-Middleware-Rewrite
The HTTP X-Middleware-Rewrite response header is an unofficial HTTP header containing the internal destination path when Next.js middleware performs a URL rewrite.
Note
The "X-" naming convention for HTTP headers, "X" referring to "experimental", has been deprecated and needs to be transitioned to the formal naming convention for HTTP headers.
Usage
Next.js middleware runs before a request reaches the
route handler. When middleware calls NextResponse.rewrite()
the browser URL stays the same while the server internally
serves content from a different path. The
X-Middleware-Rewrite header exposes the rewritten
destination, making the internal routing decision visible
in response HTTP headers.
This differs from a redirect where the browser receives a Location header and navigates to a new URL. A rewrite is transparent to the end user. The header appears on responses from Next.js applications deployed on Vercel and contains the full internal path the server resolved to, often including query parameters added by the middleware logic.
The header pairs well with X-Matched-Path for understanding the full routing pipeline. X-Matched-Path shows which route pattern handled the request while X-Middleware-Rewrite reveals the rewritten destination the middleware selected. Together with X-Vercel-Id these headers provide a complete trace of request handling on Vercel's infrastructure.
Values
Rewritten path
The value is the internal URL path the server used to resolve the response. The path often includes query parameters appended by the middleware, such as locale identifiers or site configuration values.
Proxy path
When middleware rewrites to an API route or proxy endpoint, the value reflects the internal API path. This pattern is common for proxying external services through a Next.js application.
Example
A request to a partner page was rewritten by middleware
to an internal path matching the locale-specific route.
The browser URL remained /en-us/partners while the
server resolved the content from the rewritten path.
X-Middleware-Rewrite: /en-us/partners
Middleware on an internationalized site rewrote the request to an internal path with locale and site configuration parameters. The original URL was a clean public path, but the server needed additional context to select the correct content variant.
X-Middleware-Rewrite: /en-us/_sites/us/en-us/hk-en/dogs/breeds/beagle?sc_lang=en-us&sc_site=US
A product listing page was rewritten to an internal search endpoint. The middleware translated the SEO-friendly URL into an API-backed route with the original path passed as a query parameter.
X-Middleware-Rewrite: /algolia-plp?seoUrl=%2FTuners.gc
Middleware rewrote a request to an API proxy route. This pattern is common when a Next.js application proxies external services through its own middleware layer.
X-Middleware-Rewrite: /api/proxy
Takeaway
The X-Middleware-Rewrite header reveals the internal destination path when Next.js middleware performs a URL rewrite. The value exposes the server-side routing decision while the browser URL remains unchanged, making middleware behavior visible for debugging and request tracing.