X-Middleware-Rewrite
When Next.js middleware rewrites a URL internally, the X-Middleware-Rewrite unofficial response header exposes the destination path the server resolved behind the scenes.
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