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

By Daniel Zoghalchali·Latchkey

Netlify ran your build command and it exited non-zero, so the build is marked failed. The real error is in the build log above this line; Netlify only reports that the command did not succeed.

What this error means

The Netlify build log ends with "Error: Build script returned non-zero exit code: 2" (or another code) and "Failing build: Failed to build site".

Error: Build script returned non-zero exit code: 2
Failing build: Failed to build site

Common causes

The build command itself failed

A compile error, a failing test in the build, or a thrown exception returned a non-zero code that Netlify surfaces.

A missing dependency or env var in the build image

The build needs a package or environment variable present locally but absent in the Netlify build environment.

How to fix it

Read the build log above the failure

1. Scroll up to the first error printed by the build command.
2. Reproduce it locally with the same Node version and command.
3. Fix it, then trigger a new deploy.

Set required build env vars and Node version

Add missing environment variables in site settings and pin the Node version so the Netlify build matches local.

[build.environment]
  NODE_VERSION = "20"

How to prevent it

• Run the build command in CI before deploying.
• Define build env vars in site settings or netlify.toml.
• Pin NODE_VERSION so build images match local.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation