Netlify build failed

Updated 11 October 2026

Short answer

Open the failed deploy in Netlify and read the deploy log, which records everything that happened during the build, including errors. Find the first error, not the last line. The usual causes are the build command failing, an environment variable that's set on your computer but not in Netlify, a different Node.js version, or (if the log shows exit status 128) a broken link between Netlify and your Git repository, which Netlify's docs suggest fixing by relinking the repo.

What's the problem

A deploy shows "Failed", "Build script returned non-zero exit code", or "exit status 128", and your site stays on the previous version.

Why it happens

  • The build command fails: a code error, a failing test, or a missing package.
  • Environment variables the build needs aren't set in Netlify.
  • Different Node.js version from your computer.
  • The Git repository link broke (exit status 128), for example after a repo was renamed or access changed.
  • The publish directory is wrong, so the build succeeds but there's nothing to deploy.

How to fix it

  1. Open the failed deploy and read the deploy log from the first error.
  2. Run the build locally from a clean install with the same command Netlify uses.
  3. Add missing environment variables in Netlify's site settings and redeploy.
  4. Set the Node.js version to match yours.
  5. For exit status 128, relink the repository in Netlify's continuous deployment settings.
  6. Check the publish directory matches where your build puts its output.

What Preventionlabs checks

One click runs the full report on your domain. For this problem it shows whether your site loads, how fast, and where its redirects go. With Cloudflare connected, it also shows recent deploys and account changes, with their times. It has no connection to your host, so check the host's status page and logs as well.

Run your free report

Your first report is free, no card needed. Then A$50 a month, up to 10 domains. Read-only: it never changes anything.

Sources

  1. Netlify: Build troubleshooting tipsofficial docsA record of everything that happened during a build and deploy, including any errors.
  2. Netlify: Build troubleshooting tipsofficial docsIf you are seeing your build fail with exit status 128 in the deploy log

Related

Netlify not working Check Netlify's status page, then whether the latest deploy succeeded. "Page not found" on refresh usually means a single-page app is missing its rewrite rule. Vercel deployment failed Open the build logs on the deployment's page: the first error line is the cause. Usually a build command failing, a missing environment variable, or bad config. Gatsby build failed Read the first error in the build output; it names the file and step. Usual causes: data sourcing, gatsby-node.js code, a plugin, or the Node version. Next.js error Find where it happens: at build time (read the build log), on the server (your host's function logs), or in the browser (the console). Each has its own fix.

Preventionlabs is independent and not affiliated with Netlify. Product names are used only to describe the problem.

← All of Hosting