`Astro.request.headers` was used when rendering the route `$

Error message

`Astro.request.headers` was used when rendering the route `${routePattern}'`. `Astro.request.headers` is not available on prerendered pages. If you need access to request headers, make sure that the page is server-rendered using `export const prerender = false;` or by setting `output` to `"server"` in your Astro config to make all your pages server-rendered by default.

What it means

During prerendering there is no incoming request, so request.headers only holds placeholder values. getRequest replaces the headers property with a getter that warns when a prerendered route reads it and returns the meaningless build-time headers — logic depending on real headers (auth, cookies, locale) silently misbehaves.

Source

Thrown at packages/astro/src/core/request.ts:84

		method: method,
		headers: headersObj,
		// body is made available only if the request is for a page that will be on-demand rendered
		body: isPrerendered ? null : body,
		...init,
	});

	if (isPrerendered) {
		// Warn when accessing headers in SSG mode
		let _headers = request.headers;

		// We need to remove descriptor's value and writable properties because we're adding getters and setters.
		const { value, writable, ...headersDesc } =
			Object.getOwnPropertyDescriptor(request, 'headers') || {};

		Object.defineProperty(request, 'headers', {
			...headersDesc,
			get() {
				logger.warn(
					null,
					`\`Astro.request.headers\` was used when rendering the route \`${routePattern}'\`. \`Astro.request.headers\` is not available on prerendered pages. If you need access to request headers, make sure that the page is server-rendered using \`export const prerender = false;\` or by setting \`output\` to \`"server"\` in your Astro config to make all your pages server-rendered by default.`,
				);
				return _headers;
			},
			set(newHeaders: Headers) {
				_headers = newHeaders;
			},
		});
	}

	return request;
}

View on GitHub (pinned to 52e6c34790)

Solutions

Opt that page into SSR: add `export const prerender = false;` at the top of the file
Set output: 'server' in astro.config when most pages need request data
Move the header-dependent logic out of the prerendered page (client-side script, middleware, or an API endpoint)

Example fix

// src/pages/dashboard.astro — before
export const prerender = true;
const token = Astro.request.headers.get('authorization');

// after
export const prerender = false; // server-render so headers are real
const token = Astro.request.headers.get('authorization');

Defensive patterns

Strategy: validation

Validate before calling

export const prerender = true;
const ua = prerender ? undefined : Astro.request.headers.get('user-agent');

Prevention

Audit every Astro.request.headers/cookies access when flipping a page to prerendered
Group header-dependent routes under output 'server' or per-page prerender = false
Centralize header reads in a helper that takes the value as an explicit argument so static pages cannot call it

When it happens

Trigger: A page with prerender enabled (default under output 'static', or export const prerender = true) reads Astro.request.headers or calls .get() on it in frontmatter or components.

Common situations: Copying header/cookie logic from an SSR page into a static one; switching output from 'server' to 'static' without flagging header-dependent pages; reading user-agent or cookie-based theming on a marketing/blog page.

Related errors

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/475e6e82dbeb844c. Report an issue: GitHub.