Netlify "Build script returned non-zero exit code" - Fix in CI

Netlify ran your build command and it exited non-zero, so the deploy was aborted. The real failure is in your build - a compile error, a missing variable, or a wrong command/base directory.

What this error means

The Netlify deploy log ends with Build script returned non-zero exit code: <n> after the build output. The underlying error appears just above it. It reproduces locally with the same command and env.

Netlify deploy log

9:14:02 AM: $ npm run build
9:14:30 AM: error during build: Cannot find module './missing'
9:14:30 AM: Build script returned non-zero exit code: 2

Common causes

A real build failure

A compile error, failing import, or test invoked by the build makes the command exit non-zero. Netlify reports the exit code; the cause is in the lines above.

Wrong command, base, or missing env var

An incorrect command/base in netlify.toml, or a build-time variable set locally but not in Netlify’s site settings, makes the build fail only in the cloud.

How to fix it

Reproduce and fix the underlying error

Run the exact build locally and read the error above the exit-code line.

Terminal

npm ci && npm run build

Pin command, base, and env in netlify.toml

Set the build command, base directory, and publish directory explicitly, and configure env vars in Site settings.

netlify.toml

[build]
  base = "frontend/"
  command = "npm run build"
  publish = "frontend/dist"

How to prevent it

Run the production build in PR CI before it reaches Netlify.
Configure all build-time env vars in Netlify Site settings.
Version netlify.toml so command/base/publish are explicit and consistent.