Netlify Build Failed

How to fix it

Try these in order — the most common fix is first.

1. 1. Run the build locally and read the first error in the log

   Copy steps
   1. Run your build command locally
   2. In Netlify open Deploys > the failed deploy and read the log above the generic exit code line
   Did this fix it? Yes No

2. 2. Pin the Node version

   Copy steps
   1. Set NODE_VERSION=22 (or your local major) in environment variables, or add .nvmrc to the base directory
   2. Redeploy
   Did this fix it? Yes No

3. 3. Fix warnings treated as errors

   1. Set the build command to CI='' npm run build (not CI=false)
   Did this fix it? Yes No

4. 4. Fix peer dependency conflicts

   1. Set NPM_FLAGS=--legacy-peer-deps (or --force)
   Did this fix it? Yes No

5. 5. Fix case-sensitivity

   Copy steps
   1. Run git mv OldName newname, or git rm --cached then git add, so Git records the rename
   2. Make import paths match exact casing
   Did this fix it? Yes No

6. 6. Retry with a clean cache

   1. Deploys > Trigger deploy > Clear cache and deploy site
   Did this fix it? Yes No

7. 7. Check devDependencies and env vars

   Copy steps
   1. Move build tools to dependencies or unset NODE_ENV
   2. Ensure variables have the Builds scope; .env files are not read on Netlify
   Did this fix it? Yes No

Symptoms

The deploy log ends with 'Build script returned non-zero exit code' or 'Failed during stage building site'.

Why it happens

• Node version differs from local
• Missing or uncommitted lockfile
• Case-sensitive filenames (macOS/Windows hide it)
• devDependencies skipped when NODE_ENV=production
• CI=true turns warnings into errors
• Peer dependency conflicts
• Cache corruption
• Missing environment variables

This guide also covers

• netlify build failed
• netlify build script returned non-zero exit code
• netlify deploy failed
• netlify command not found

The same problem in other apps

All export, render & quality loss guides →

• Vercel Deployment Failed: Build Error (Vercel)

Other Netlify errors

• Netlify Page Not Found on Refresh (SPA 404)
• Netlify Deploy Stuck on Building or Enqueued
• Netlify Custom Domain Not Working
• Netlify SSL Certificate Pending or Not Provisioning
• Netlify Function Timeout (502 / 504)
• Netlify Site Paused: Credit Limit Reached
• Netlify Build Failed: Secrets Scanning Detected Secrets
• Netlify Environment Variables Undefined