Fix Next.js build errors

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-nextjs-build-errors/raw' -o ~/'.claude/skills/fix-nextjs-build-errors/SKILL.md'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-nextjs-build-errors/raw' -o '.cursor/skills/fix-nextjs-build-errors/SKILL.md'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-nextjs-build-errors/raw' -o '.agents/skills/fix-nextjs-build-errors/SKILL.md'

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

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).

Licence

Licence: CC BY 4.0. Attribution when you reuse it: From TheSkillVault, https://theskillvault.ai, CC BY 4.0