Why does `next build` fail with type or lint errors that I do not see in dev, and how do I debug it?

next dev compiles pages on demand and does not type-check. next build type-checks the whole project and (in Next 15 and earlier) runs ESLint on configured directories.

Find the error

1. Read the first error, later ones are often consequences.
2. Run the type checker directly for a faster loop: npx tsc --noEmit (or your typecheck script).
3. Fix the code. Disabling checks (typescript.ignoreBuildErrors) just moves the failure to runtime.

Typical causes in Next 15

• params / searchParams typed as plain objects instead of Promise<...>.
• Page files exporting extra named values; only default, metadata, generateMetadata, revalidate and similar route options are allowed.
• Missing await on cookies() or headers().
• Date vs string mismatches after serialising props.
• Unused imports flagged by ESLint rules treated as errors.
• Types generated in .next/types are stale: delete .next and rebuild.

Process killed or heap errors

The build ran out of memory (common on small CI and Docker machines).

NODE_OPTIONS=--max-old-space-size=4096 npm run build

Also reduce parallelism, or check for huge files imported into pages. In a large repo, a plain npx tsc can run out of memory without a clear message; check the exit code (echo $?) rather than just the output.

Keep it green

Run typecheck and lint in CI on every push so errors show up in the pull request rather than at deploy time.

Pitfall: stale tsconfig.tsbuildinfo or .next/types can show errors for files you already deleted. Remove them and retry.