What this usually means
These failures almost always indicate a logic or data issue inside getStaticProps or getStaticPaths. Next.js SSG expects these functions to be synchronous or return a Promise, never throw, and always provide the right shape of data. Even a missing or undefined return will break the build silently or throw opaque errors. Third-party API calls, data-fetching mistakes, or even accidental reliance on process.env variables that aren’t available at build time can trigger these failures.
The first ten minutes — establish facts before touching code.
- 1Run `yarn build` or `npm run build` locally, and check for stack traces or error lines referencing getStaticProps/getStaticPaths.
- 2Add console.log statements at the top/bottom of getStaticProps/getStaticPaths; re-run the build to see how far these functions execute before failing.
- 3Temporarily hardcode return values in getStaticProps/getStaticPaths to rule out data dependency issues.
- 4Check if any promises inside getStaticProps/getStaticPaths aren’t properly awaited (missing await or .then).
- 5Review recent changes in external data sources/APIs used in static props generation.
The specific files, logs, configs, and dashboards that usually own this bug.
- searchpages/[slug].js and pages/index.js for getStaticProps/getStaticPaths exports
- search.next/build-manifest.json for missing or incomplete routes after build
- searchVercel or CI build logs (look for 'error' or 'failed' lines even if not at the end)
- searchAPI clients or fetch wrappers imported by SSG functions
- searchAny usage of process.env or fs in getStaticProps/getStaticPaths
- searchpackage.json scripts to confirm 'build' actually runs 'next build'
Practical causes, not theory. These are the things you will actually find.
- warninggetStaticPaths returns undefined or an empty value instead of { paths, fallback } object
- warningUnhandled exceptions thrown inside getStaticProps (e.g., fetch fails but isn’t caught)
- warningprocess.env variable missing at build time (works in dev, fails in CI)
- warningThird-party API returns incomplete or empty result; SSG functions return undefined
- warningDynamic route ([slug]) receives an empty list from getStaticPaths
- warningBad import or missing module only used at build time
Concrete fix directions. Pick the one that matches your root cause.
- buildWrap all data fetching in try/catch inside getStaticProps/getStaticPaths; throw explicit errors with context
- buildReturn default data objects if fetches fail, and log the failure for tracing
- buildExport getStaticPaths for all dynamic pages, even if returning paths: [], fallback: false
- buildUse `console.error` for any errors inside SSG functions so they appear in build logs
- buildValidate all process.env variables at the top of SSG functions and fail early if missing
A fix you cannot prove is a guess. Close the loop.
- verifiedRun `yarn build` and verify that all pages are generated in .next/server/pages/ (or .next/static/ for export builds)
- verifiedCheck build output for zero errors or warnings after fixing (don’t just trust a 'Compiled successfully' message)
- verifiedView the built site locally using `yarn start` or `npx serve out` for static export
- verifiedInspect .next/build-manifest.json and confirm all expected routes exist
- verifiedDeploy to a preview environment (Vercel or Netlify) and confirm static pages are visible
Things that make this bug worse or harder to find.
- warningAssuming that silent build means success—always check output directories and build logs
- warningLeaving uncaught async errors inside getStaticProps/getStaticPaths
- warningReturning undefined or missing the required return shape ({ props }) in SSG functions
- warningUsing dev-only environment variables or local files in SSG code
- warningSkipping hardcoded data checks—always isolate if it’s a data problem or function export problem
Next.js SSG: Dynamic Route Pages Missing After Build
Timeline
- 11:00Start deployment to Vercel; build step begins
- 11:02Vercel build logs show 'Compiled successfully', but with a warning
- 11:04QA notices /posts/first-post returns 404 after deploy
- 11:07Engineer checks .next/server/pages/ and sees /posts/index.js but not /posts/[slug].js
- 11:08Re-runs `yarn build` locally, adds console.log in getStaticPaths, sees it never executes
- 11:10Discovers typo: getStaticPaths was exported as getstaticPaths (lowercase 's')
- 11:11Fixes export, rebuilds, all expected static pages appear in output
I kicked off a Vercel deploy, which appeared to succeed, but our newly created post pages returned 404 in production. Oddly, the main /posts page worked fine.
Digging into the build artifacts, I noticed that .next/server/pages/ was missing any files for the dynamic [slug] route. Adding console.logs inside getStaticPaths, I realized these never ran during build.
Turned out the function was named getstaticPaths (typo in capitalization), so Next.js silently skipped static generation for these routes. Fixing the export to getStaticPaths and rerunning the build fixed everything instantly.
Root cause
getStaticPaths was misspelled in the export, so Next.js skipped static generation for the dynamic route.
The fix
Corrected the export to 'export async function getStaticPaths()' with exact casing.
The lesson
Always verify that your SSG functions are correctly exported and that their casing matches Next.js requirements—Next.js will not warn you in this scenario.
Next.js doesn't always surface obvious errors when getStaticPaths is missing or exported incorrectly. If you see dynamic routes missing in your build output or deployed app, always double-check the function name and export.
Adding a console.log at the top of getStaticPaths will confirm if the function is running during build. If not, the export is wrong or not picked up by Next.js.
If a fetch inside getStaticProps or getStaticPaths fails (network issue, API returns 500, etc.), and you don't catch the error, Next.js will terminate the build or skip that page without a clear error.
Wrap your fetch calls like this: `try { ... } catch(e) { console.error('getStaticProps error', e); throw e; }` so you see useful tracebacks during build.
Next.js static generation runs at build time, which means only environment variables present in your build environment are accessible. Local dev may have different .env files than CI.
To avoid surprises, explicitly check for required process.env variables at the start of getStaticProps/getStaticPaths and fail the build early if missing.
After any SSG build, check the physical output: for server builds, look in .next/server/pages/; for static exports, check out/ directory.
Missing files for dynamic routes always point to a getStaticPaths or getStaticProps misconfiguration.
Frequently asked questions
Why does my build pass but dynamic pages are missing?
Next.js won't fail the build if getStaticPaths or getStaticProps are missing or misnamed—those pages will simply not be generated. Always verify your output files.
What happens if getStaticProps throws an exception?
The build will fail for that page, sometimes taking down the whole build. Wrap all async code in try/catch and emit errors to logs for fast diagnosis.
Can I use process.env in getStaticProps?
Yes, but only variables present at build time. Missing env vars in CI are a common cause of silent build failures or incomplete pages.
How can I debug which getStaticPaths or getStaticProps functions are running?
Instrument each with console.log at entry/exit and re-run the build. Check your build logs for these outputs.
Do I need to export getStaticPaths for every dynamic route?
Yes. If you have a file like pages/posts/[slug].js, failing to export getStaticPaths will mean no static pages are created for that route.