Detect static rendering to use headers conditionally

[finom]

Summary

I work on a lib that from the client-side sends an optional header to the server that works at a route.ts GET handler. The route.ts file can be optionally rendered statically with output: export defined at the next config. The header works fine in dynamic environment, but when it's rendered on build time I get:

Error occurred prerendering page "/api/spec/v3/meta.json". Read more: https://nextjs.org/docs/messages/prerender-error
Error: Route /api/[[...vovk]] with `dynamic = "error"` couldn't be rendered statically because it used `headers`. See more info here: https://nextjs.org/docs/app/building-your-application/rendering/static-and-dynamic#dynamic-rendering

...because I use req.headers object (not the headers function).

This makes sense, but in order to fix that I need to use headers conditionally: if we're in static env, don't attempt to access headers, else work normally in other case. Is there an API of this kind, that allows to detect static rendering?

Additional information

No response

Example

No response

[SametDulger]

Yes, your understanding is correct. During static generation, request-specific APIs like headers() or req.headers are not available since there is no request.

Next.js does not currently provide a built-in isStaticGeneration flag, but you can handle this situation safely using the following approaches:

1. Use try/catch around headers() to detect the environment

import { headers } from 'next/headers';

let headerValue: string | null = null;

try {
  const hdrs = headers();
  headerValue = hdrs.get('x-my-header');
} catch {
  // Likely running in static generation
  headerValue = null;
}

This is the most reliable and straightforward way to prevent build-time errors.

2. Use process.env.NEXT_PHASE (may not be fully reliable)

const isStatic = process.env.NEXT_PHASE === 'phase-export';

This works in many cases but might not reflect the exact rendering phase in some environments.

3. Use export const dynamic = 'force-dynamic' to prevent static rendering

If your route depends on runtime-only features like request headers, you can tell Next.js to always render it dynamically:

export const dynamic = 'force-dynamic';

This disables static rendering for that route.

• Prevent headers() from crashing during static builds ---> Use try/catch
• Detect static build time ---> Use process.env.NEXT_PHASE (optional)
• Force dynamic behavior ---> Use export const dynamic = 'force-dynamic'
• Conditionally use headers ---> Wrap access in try/catch or checks

[finom]

try..catch method works perfectly, thanks!