Error: Build failed
Command "npm run build" exited with 1

Your Vercel deployment failed during the build step. Here are the most common causes.

Fix 1: Missing Environment Variables

The #1 cause of Vercel build failures. Your code references an env var that exists locally but not on Vercel.

Error: Missing required environment variable: DATABASE_URL

Fix: Add the variable in Vercel Dashboard → Settings → Environment Variables.

Make sure to set it for the right environment (Production, Preview, Development).

Fix 2: TypeScript Errors

Vercel runs tsc in strict mode. Errors that VS Code ignores might fail the build.

# Test locally first
npm run build

Common issues:

• Unused variables (noUnusedLocals in tsconfig)
• Missing types (npm install -D @types/node)
• any types when strict: true

Quick fix (not recommended long-term):

// tsconfig.json
{
  "compilerOptions": {
    "strict": false
  }
}

Fix 3: ESLint Errors Treated as Build Errors

Next.js treats ESLint errors as build failures by default.

// next.config.js — ignore ESLint during build
module.exports = {
  eslint: {
    ignoreDuringBuilds: true,
  },
}

Or fix the actual ESLint errors:

npx next lint --fix

Fix 4: Wrong Node.js Version

Vercel might use a different Node version than your local machine.

Fix: Specify the version in package.json:

{
  "engines": {
    "node": "20.x"
  }
}

Or in Vercel Dashboard → Settings → General → Node.js Version.

Fix 5: Dependencies Not Installing

Module not found: Can't resolve 'some-package'

Check if the package is in dependencies (not just devDependencies):

# Move from dev to regular dependencies
npm install some-package --save

Vercel only installs devDependencies if your build command needs them. For frameworks like Next.js, build tools should be in devDependencies and runtime packages in dependencies.

Fix 6: Build Command Wrong

Check your Vercel project settings:

• Build Command: npm run build (or next build, astro build, etc.)
• Output Directory: .next (Next.js), dist (Astro/Vite), build (CRA)
• Install Command: npm install

Fix 7: Memory Limit

FATAL ERROR: Reached heap limit Allocation failed

Vercel has memory limits. Fix:

{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' next build"
  }
}

See also: Node heap out of memory fix

Debugging Tips

1. Always test locally first: npm run build should succeed before pushing
2. Check Vercel build logs: Dashboard → Deployments → click the failed deploy → Build Logs
3. Match your local environment: same Node version, same env vars
4. Use vercel build locally: npx vercel build simulates the Vercel build environment