X-Matched-Path
The HTTP X-Matched-Path response header is an unofficial HTTP header indicating the route pattern a Next.js application matched for the incoming request.
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 applications deployed on Vercel include the X-Matched-Path header in responses. The value contains the file-system route pattern from the Next.js pages or app directory handling the request. This maps the final URL back to the source route definition, making route debugging and request tracing straightforward.
The header is useful when diagnosing routing issues in applications with dynamic segments, catch-all routes, or localized paths. Comparing the requested URL to the matched pattern confirms whether the correct route handled the request. The header pairs naturally with X-Vercel-Id for full request tracing across Vercel's infrastructure.
A related header named X-Nextjs-Matched-Path appears
in standalone Next.js deployments. This header is
internal to the Next.js Pages Router, used for data
request routing when middleware matchers are present.
Unlike X-Matched-Path, which is a public response
header from Vercel's edge network, the Next.js variant
is router machinery and rarely visible in production
responses.
Values
Static path
A value like / or /robots.txt indicates the request
matched a static route defined directly in the pages or
app directory. The path corresponds exactly to the file
path in the Next.js project.
Dynamic segment
A value containing brackets like /news/[slug] or
/residential/location/[state]/[city] indicates a
dynamic route. Each bracketed segment is a URL parameter
extracted at request time. The pattern mirrors the
file-system naming convention Next.js uses for dynamic
routes.
Catch-all route
A value using the spread syntax like /[...not-found]
or /api/media/...uri indicates a catch-all route.
Single brackets with three dots ([...param]) match one
or more path segments. Double brackets
(...param) create an optional catch-all also
matches the root of the pattern.
Localized path
A value prefixed with a locale segment like /fr or
/en-GB/dashboard/population/...state indicates
Next.js internationalized routing. The locale prefix
is part of the matched route pattern.
Error path
A value of /404 or /_error indicates the request
did not match any defined route and fell through to the
error page. This appears when Next.js serves its
built-in 404 or custom error page.
Example
A request to the homepage matched the root static route.
This is the simplest pattern, corresponding to an
index page file.
X-Matched-Path: /
A request to a news article matched a dynamic route with
a [slug] parameter. The actual URL segment (the article
title or identifier) was captured by the slug variable.
X-Matched-Path: /news/[slug]
A request matched a deeply nested dynamic route with multiple URL parameters. Each bracketed segment extracts a different part of the URL path.
X-Matched-Path: /residential/location/[state]/[city]
A request matched an optional catch-all route. The double bracket syntax means the route handles both the base path and any number of additional segments.
X-Matched-Path: /en-GB/dashboard/population/...state
A request matching no defined route fell through to the 404 error page.
X-Matched-Path: /404
Takeaway
The X-Matched-Path header shows which Next.js route pattern handled a request on Vercel. The value maps URLs back to their source route definitions, making routing issues easier to diagnose.