{"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.","category":"debugging","tags":["nextjs","debugging","typescript","vercel"],"models":["any"],"proven":false,"passing_families":0,"model_testing":"Not yet model-tested; testing Jan 2027","url":"https://theskillvault.ai/skills/fix-nextjs-build-errors","api_url":"https://theskillvault.ai/api/skills/fix-nextjs-build-errors","raw_url":"https://theskillvault.ai/api/skills/fix-nextjs-build-errors/raw","body":"# Fix Next.js build errors\n\n`next dev` is forgiving and `next build` is strict. Most build failures fall into a handful of patterns.\n\n## When to use\n- `npm run build` fails locally or the Vercel deploy log shows \"Build failed\".\n- The app works in development but not once built.\n- You see \"Error occurred prerendering page\" or \"Module not found\".\n\n## When not to use\n- The build passes but the page breaks in the browser with a hydration warning. Use fix-react-hydration-errors.\n\n## Steps\n1. Run `npm run build` locally so you can repeat the error quickly.\n2. Scroll up to the first error, not the last line. Later errors are often side effects.\n3. Type errors: fix the reported file and line. Do not set `ignoreBuildErrors` to hide them.\n4. \"Module not found\": check the path case (Linux is case-sensitive), the import alias in `tsconfig.json`, and that the package is in `dependencies`.\n5. \"You're importing a component that needs useState\": add `\"use client\"` to that component, or move the hook into a small client component.\n6. 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.\n7. 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.\n8. Missing env vars: make sure the host has them for the build step, and that browser values start with `NEXT_PUBLIC_`.\n9. Clear `.next` and reinstall with `rm -rf .next node_modules && npm ci` if errors make no sense.\n10. Rebuild, then deploy again and confirm the build log is green.\n\n## Gotchas\n- Never move a secret into a `NEXT_PUBLIC_` variable to fix a build. It will ship to every browser.\n- Lockfile out of sync with `package.json` makes CI install different versions. Commit the lockfile.\n- A different Node version on the host can break builds. Pin it in `package.json` engines or the host settings.\n- Disabling ESLint or TypeScript in the build hides real bugs until users find them.\n\n## Portability\nWorks 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.\n\n## Example prompt\n\"My Next.js app works with npm run dev but Vercel says Build failed. Here is the log. Find the cause and fix it.\"\n\n## Done when\n- `npm run build` passes locally with no ignored errors.\n- The hosted deploy builds green.\n- The cause is written in the commit message.\n\n---\nHouse original by TheSkillVault (CC-BY-4.0).","files":[],"license":"CC-BY-4.0","license_name":"CC BY 4.0","license_url":"https://creativecommons.org/licenses/by/4.0/","attribution":"From TheSkillVault, https://theskillvault.ai, CC BY 4.0","install":{"claude_code":"curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-nextjs-build-errors/raw' -o ~/'.claude/skills/fix-nextjs-build-errors/SKILL.md'","cursor":"curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-nextjs-build-errors/raw' -o '.cursor/skills/fix-nextjs-build-errors/SKILL.md'","agents":"curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-nextjs-build-errors/raw' -o '.agents/skills/fix-nextjs-build-errors/SKILL.md'","mcp_url":"https://theskillvault.ai/mcp","cursor_mcp_deeplink":"cursor://anysphere.cursor-deeplink/mcp/install?name=theskillvault&config=eyJ1cmwiOiJodHRwczovL3RoZXNraWxsdmF1bHQuYWkvbWNwIn0%3D","mcp_config":{"mcpServers":{"theskillvault":{"url":"https://theskillvault.ai/mcp"}}}},"bundles":[],"tested_on":[{"family":"chatgpt","name":"ChatGPT","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"claude","name":"Claude","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"gemini","name":"Gemini","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"grok","name":"Grok","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"llama","name":"Llama","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"deepseek","name":"DeepSeek","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"mistral","name":"Mistral","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"qwen","name":"Qwen","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"kimi","name":"Kimi K","outcome":null,"date":null,"source":null,"counts":false,"stale":false}],"proven_rule":{"threshold":5,"window_days":365,"computed_at":"2026-11-02T03:20:33.817Z"}}