next build stops with: Failed to collect page data for a route
> Build error occurredShort answer
Failed to collect page data for a route is the last line of a failed build, not the cause. The real error is printed above it. Rebuild with --debug-prerender to get readable stack traces, then check for code that runs at build time and throws, a slow path that times out, or a dynamic route without generateStaticParams.
Fix it fast
1Find out which cause you have
Rebuild with readable traces. The error above the 'Failed to collect page data' line names the file; the flag turns off minification and adds server source maps.
npx next build --debug-prerender2Match what you see, then jump to its fix
- 1
The error above the wrapper line mentions an undefined variable, a failed connection or a failed fetch for that routeRoute code runs during the build and throwsFix - 2
Error: Page "/guides/[id]": `ensureStatic = "navigation"` requires an exported `generateStaticParams()` function.A route that must be static has no generateStaticParamsFix - 3
Collecting page data timed out after multiple attemptsPage data collection timed outFix
- 1
What does the error look like?
> Build error occurredError: Failed to collect page data for /dashboardCollecting page data timed out after multiple attempts
Cause 1 of 3
Route code runs during the build and throws
1Check
next build prerenders eligible routes, so top-level code and data reads in that route run on the build machine. Environment variables from .env are loaded at build; variables that only exist on the server at runtime, or a database that is not reachable from the build machine, make the route fail.
npx next build --debug-prerender --debug-build-paths="app/dashboard/page.tsx"2Fix
Read runtime-only values during request time instead of build time. In the App Router, awaiting connection() before reading the value makes the route render on request.
import { connection } from 'next/server'
export default async function Page() {
await connection()
const value = process.env.MY_VALUE
// ...
}3Verify
Build again and check that the route shows as dynamic in the route table.
npx next buildConfirmed by nextjs.org
Cause 2 of 3
A route that must be static has no generateStaticParams
1Check
With ensureStatic set on a dynamic route, the build needs at least one param value to prerender. The build log prints the specific requirement just above the wrapper line.
grep -rn "ensureStatic" app/2Fix
Export generateStaticParams and return at least one value.
export const ensureStatic = 'navigation'
export async function generateStaticParams() {
return [{ id: 'first-guide' }]
}3Verify
Rebuild; the listed path appears in the route table.
npx next buildConfirmed by nextjs.org
Cause 3 of 3
Page data collection timed out
1Check
Next.js restarts the page data workers when no progress happens for a while, and fails after repeated attempts. A promise that never settles, an infinite loop, or a very slow network request in static params code causes it.
grep -rn "staticPageGenerationTimeout" next.config.*2Fix
Make every promise in your static path code resolve or reject, avoid very long network timeouts, and only if the work is truly slow raise the timeout (default is 60 seconds).
// next.config.js
module.exports = {
staticPageGenerationTimeout: 120,
}3Verify
Rebuild and watch that it finishes without restarting workers.
npx next buildConfirmed by nextjs.org
How do I stop it coming back?
- Read the lines above 'Failed to collect page data' first; fix that error, not the wrapper.
- Do not open database or API connections at module top level in route files.
- Keep runtime-only secrets for request time, and give the build machine the variables that routes need at build time.
- Use --debug-build-paths to rebuild one failing route instead of the whole app.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
create-next-app keeps creating a TypeScript project
Would you like to use TypeScript? No / Yes
create-next-app now makes a TypeScript project by default.
2 causes, each with a fixBack end
Show a custom sign-in error in NextAuth without leaving the page
http://localhost:3000/api/auth/error?error=...
By default a failed NextAuth credentials sign-in navigates to the error page with the message in the URL.
3 causes, each with a fixBack end
Request body is rejected as too large in Next.js (1 MB default)
413 Payload Too Large
Next.js limits request bodies to 1 MB by default, in both Pages Router API routes and Server Actions.
3 causes, each with a fixBack end
Next.js server code cannot connect to its own API on 127.0.0.1
Error: connect ECONNREFUSED 127.0.0.1:3003
ECONNREFUSED means nothing was listening at that address and port when the server-side fetch ran.
2 causes, each with a fixBack end
TypeError: Failed to parse URL when a Next.js server fetches its own API
TypeError: Failed to parse URL from undefined/api/test
Server code has no page address, so fetch('/api/test') cannot be turned into a full URL and throws Failed to parse URL.
3 causes, each with a fixBack end
next start says it could not find a production build
next start fails before the server listens on any port
next start only serves a finished build, it does not create one.
3 causes, each with a fix