Proxy headers

The two directions are easy to confuse. NextResponse.next({ request: { headers } }) makes headers available upstream to the render. NextResponse.next({ headers }) sends them downstream to the client.

You cannot modify request.headers in place. Clone it into a new Headers object first.

What to check

Request side (what the render sees) is the panel below. It is a dynamic hole because headers() is a runtime API, which a cached scope cannot read.

Response side (what the client sees) needs curl, since the page cannot read its own response headers:

curl -sI localhost:3000/proxy/headers | grep -i x-proxy

Correlate them. The x-proxy-invocation response header and the x-from-proxy-invocation request header are set to the same id in one invocation, so they should match for a given request. A match proves both directions came from the same proxy call.

Keep them small. Large headers can trigger 431 Request Header Fields Too Large depending on the upstream server.

Injected request headers

What the render received

dynamic (request time)

ran at 00:34:32.021Zexec zkshobage …

x-from-proxy-invocation: 0b4a7334
x-from-proxy-geo: unknown

The geo value is a stand-in: locally there is no CDN in front, so it reads unknown. Behind Pantheon’s CDN the proxy would forward a real header from the edge. That is the useful case for injecting a request header, because the render cannot compute the value itself.

A dynamic hole by necessity: headers() and cookies() are runtime APIs, so this subtree resolves per request while the rest of the page stays prerendered.

What the render received

suspense fallback

streaming at request time. This is what ships in the static shell.

Reference

header	direction	how to read it
x-from-proxy-invocation	request to render	headers() in a dynamic scope
x-from-proxy-geo	request to render	headers() in a dynamic scope
x-proxy-invocation	response to client	curl -sI, or devtools
x-proxy-branch	response to client	curl -sI, or devtools
x-proxy-prefetch	response to client	curl -sI with a prefetch header
x-proxy-path	response to client	curl -sI (pre-rewrite pathname)