---
name: fix-nextjs-build-errors
description: Fixes a Next.js build that fails on next build or in a Vercel deploy - read the first real error, then work through type errors, server-only code in client components, missing env vars at build time, bad imports and prerender failures. Use when next build fails, a Vercel build log is red, or the app runs in dev but will not build.
license: CC-BY-4.0
metadata:
  category: debugging
  tags: "nextjs,debugging,typescript,vercel"
  author: johnny-bravo
  version: "1.0"
  updated: "2026-11-02"
  status: published
  aliases: "next build failed, vercel build error, build log"
---

# Fix Next.js build errors

`next dev` is forgiving and `next build` is strict. Most build failures fall into a handful of patterns.

## When to use
- `npm run build` fails locally or the Vercel deploy log shows "Build failed".
- The app works in development but not once built.
- You see "Error occurred prerendering page" or "Module not found".

## When not to use
- The build passes but the page breaks in the browser with a hydration warning. Use fix-react-hydration-errors.

## Steps
1. Run `npm run build` locally so you can repeat the error quickly.
2. Scroll up to the first error, not the last line. Later errors are often side effects.
3. Type errors: fix the reported file and line. Do not set `ignoreBuildErrors` to hide them.
4. "Module not found": check the path case (Linux is case-sensitive), the import alias in `tsconfig.json`, and that the package is in `dependencies`.
5. "You're importing a component that needs useState": add `"use client"` to that component, or move the hook into a small client component.
6. Server-only code (database, `fs`, secret keys) imported by a client component: move it to a server component, a route handler or a server action.
7. Prerender errors: the page calls an API or env var at build time. Add a fallback, make the page dynamic, or set the env var in the build environment.
8. Missing env vars: make sure the host has them for the build step, and that browser values start with `NEXT_PUBLIC_`.
9. Clear `.next` and reinstall with `rm -rf .next node_modules && npm ci` if errors make no sense.
10. Rebuild, then deploy again and confirm the build log is green.

## Gotchas
- Never move a secret into a `NEXT_PUBLIC_` variable to fix a build. It will ship to every browser.
- Lockfile out of sync with `package.json` makes CI install different versions. Commit the lockfile.
- A different Node version on the host can break builds. Pin it in `package.json` engines or the host settings.
- Disabling ESLint or TypeScript in the build hides real bugs until users find them.

## Portability
Works for Next.js 13-15 with the App Router or Pages Router. If you deploy on Netlify, Cloudflare or a Docker host instead of Vercel, the same errors show in that build log.

## Example prompt
"My Next.js app works with npm run dev but Vercel says Build failed. Here is the log. Find the cause and fix it."

## Done when
- `npm run build` passes locally with no ignored errors.
- The hosted deploy builds green.
- The cause is written in the commit message.

---
House original by TheSkillVault (CC-BY-4.0).