Next.js "Error occurred prerendering page" in CI

By Kaveh Alemi·Latchkey

During next build, Next.js renders pages to static HTML at build time. If your component or its data fetching throws while running on the server with no request context, the build reports a prerender error and aborts.

What this error means

next build stops with "Error occurred prerendering page '/path'" and a stack trace, often referencing window, document, a failed fetch, or undefined data during static generation.

Error occurred prerendering page "/dashboard". Read more:
https://nextjs.org/docs/messages/prerender-error
ReferenceError: window is not defined
    at Dashboard (/app/dashboard/page.js:12:3)

Common causes

Browser-only APIs run during server prerender

Accessing window, document, or localStorage at module or render time throws because prerendering runs in Node with no DOM.

Data fetching fails or returns undefined at build time

A fetch to an unreachable host, or code that assumes data is present, throws while the page is generated statically.

How to fix it

Guard browser APIs or defer to the client

1. Move browser-only access into useEffect, which never runs during prerender.
2. Guard direct access with typeof window !== 'undefined'.
3. For purely client UI, mark the component with 'use client' and avoid server access.

useEffect(() => {
  const w = window.innerWidth
  // ...
}, [])

Make build-time data fetching resilient

Handle non-OK responses and missing data so a flaky upstream does not throw during static generation.

const res = await fetch(url)
if (!res.ok) return { posts: [] }
const posts = await res.json()

How to prevent it

• Keep browser-only code inside effects or client components.
• Handle fetch failures gracefully in server components.
• Run next build in CI so prerender errors surface before deploy.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation