Category: Next.js, React and TypeScript

Next.js: read headers() blocks static prerendering

Read this guide in Polish

The page was previously statically generated, and after adding headers() it switches to dynamic mode or build reports a warning. Reading headers depends on a specific request and can prevent the whole route from being executed as a permanent HTML at build.

How to identify the source of the problem

Check where you call headers() and whether the component is used by all subpages in the layout. Verify whether the required information actually depends on the request, or whether it is a constant configuration of the application.

Compare the message from the console with the result of the production compilation and the condition after the page has been refreshed.

Repair steps

Move header-dependent logic to a clear dynamic route or a smaller separated fragment. For public content, use a fixed configuration when the header is not required for rendering.

How to Test Solution

The routes have intended rendering mode, and build does not accidentally change it by a common layout.

Security and restrictions

Do not try to read private user headers in statically generated HTML.