[Support Guide] Debugging Netlify site builds

Last checked by Netlify Support: December 2022

Note: This article is only about builds within Netlify’s Continuous Integration (CI) environment, as triggered from git commits or from incoming build webhooks. You can learn more in depth about how Netlify builds your site in this article about how our build bots build sites.

Some background

There are a fair number of reasons that a build could fail in Netlify’s CI environment, even if building works locally. Testing locally is always the place to start, and the thing we will recommend to you first when asking for help. Further, you should make sure your build works locally from a fresh clone of the respective branch of your repository. An existing local copy of your code can have local changes that are not reproduced by a git clone, which is how our build network fetches your code, before starting your build.

Note also that there is no “cache” of your build - we cache only your dependencies, NOT the actual files from the last build - those are on our CDN but not available directly during build. The intended use pattern is: “check all the files you need to regenerate your site into git, and let us regenerate the site completely each build from that source code”. It’s an antipattern to commit your node_modules folder or pre-built files already in your publish directory, unless you are NOT having us build your site.


The most likely reason for a build failure on Netlify happens when our build environment isn’t configured to match your local environment. There are other reasons as well, which you can read more about here, in our article on troubleshooting build problems, but the version mismatch is the probable reason for problems. This article describes all the possible build settings and versions and how to set them, so it is a great place to start when reviewing our configuration versus your local configuration. Read on for more detailed advice on what to try for your build to get it working!

Since most of our builds use Node.js/Javascript, you should make sure that we build using the same versions of Node.js, npm, and the same Node environment settings that you do locally. To check that, you can simply run node -v in the terminal.

Our current default versions as of December 2022 (though subject to upgrade at any time) are:

  • a NODE_ENV setting of development
  • Node v16 (any version that nvm can install)
  • NPM - Any version available via NPM (default with that version of Node)
  • Yarn v1.22.19 (any version available via their installer) (note that we only install Yarn automatically if you have a yarn.lock file. If you mean to use Yarn but don’t have a yarn.lock in your repository, add Yarn to your package.json so we install it for you before you try to use it :slight_smile: )

You can adjust those versions as follows:

  • Set the Node.js environment with the NODE_ENV variable
  • Set a NODE_VERSION environment variable from the “Build and Deploy” site settings page in our UI - in the “Build Environment” section. The value inside can be anything you would use with nvm (eg 8 or 10.11.2). You can also use a .nvmrc file with this number in it.
  • Set the npm version by setting an NPM_VERSION variable
  • Set a Yarn version with the YARN_VERSION variable

If your build is hanging or terminating abruptly, you could be using too much memory or trying to deploy so many new files we can’t complete the deploy in the default time limits. This post has some more information on those limits and how to troubleshoot.

What next?

In case that doesn’t help you fix your build, the easiest way to debug your build in our environment is to pull down the Docker container that we use as a build image and use it interactively. You must first install Docker (it’s free!) from this website or use your preferred package manager. Then, using a fresh clone of your repo, follow the steps outlined in this doc to use our build container locally: GitHub - netlify/build-image: This is the build image used for running automated builds

Should you have a site that uses plugins - particularly essential ones like gatsby or nextjs - you can and should test a build in our CLI. This will let you see a bit more about what files are generated, and the output is a better representation of what our CI does than the advice above about testing in our docker build image. This workflow is described in this article: Get started with Netlify CLI | Netlify Docs

In case that still doesn’t help, don’t give up! Please start a new thread, link to this one, and tell us the information you gathered while debugging:

  • a link to your most recent deployment attempt in our UI (should start with https://app.netlify.com/sites/…). This will only help the community debug in case your build logs are public, of course. Most public repositories are set with public build logs, and our Support team can by request make your own site’s build logs public even if it’s a private repository.
  • include the specific log line you think the error is in, from that latest deploy you tried to debug and have linked. Make sure you find the root cause error line - Build script exited with Error 1 is a SYMPTOM of some prior error from your build script :slight_smile:
  • give a short, succinct rundown on what you have tried so far and we’ll try to help.
Error running command: Build script returned non-zero exit code: 1
[Support Guide] Frequently encountered problems during builds
Gatsby builds only failing on Netlify
Netlify deployment fails with message: failed during stage 'building site': Build script returned non-zero exit code: 127
Build fails on push but not when locally built and deployed using Netlify CLI
Trouble installing NPM packages
Plugin "@netlify/plugin-nextjs" failed
Production build fails due to eslint `console.log()` errors, possible issue with NODE_ENV
Problems with deploy of my website, from today
I'm having trouble getting my website to load
Cant deploy Create React App site
Deployment Error
Failed Building production JavaScript and CSS bundles - Build script returned non-zero exit code: 1
Vue site automatic compilation fails
Deployment and Netlify Build Image Errors
Unable to build due to waiting for capacity
Error during build Angular App
Deploying a phoenix app on netlify
Not able to see changes to the deployed site
GraphQL...unix error: No such file or directory
Help with deploying on netlify
Tried deploying my first project, but no luck
I am getting an error whenever I try automatic deployment with GitHub
Netlify doesn't install dependencies, build script only works by manually adding `npm install`
All builds fail after 30 seconds, even previously successful ones
No mime type for file with extension gifsupported
Gridsome build fails due to plugin
Updating node modules
Components rendering in localhost but not deploying
"Deploy to Netlify" button doesn't work as expected
Svelte 'Sapper' build not recognizing JS optional chaining operators in Netlify
Gatsby deployment problem
Could not find module "@parcel/transformer-webmanifest"
[Support Guide] What can I do if my build fails for memory-overallocation-related errors?
[Support Guide] What can Netlify's staff help debug about my failing builds or deploys?
Nuxt is compiling Firebase Functions
[Support Guide] Build Performance Pro-tips
Build with sharp/libvips
[Support Guide] How do I access private repositories in the build environment?
[Support Guide] How can I optimize my Netlify build time?
Support Guides - Or, how to find answers for frequent questions!
[Support Guide] My site deploy fails unless Netlify's build cache is cleared
Public build logs for a private repo site
Public build logs for a private repo site
Local build looks very different from build version
Vuetify Button Fab not appearing the same on netlify as on my local environment
Deploy error Unable to find theme Directory
Error: [BABEL] /opt/build/repo/src/index.tsx: Cannot find module '@babel/helper-call-delegate'
Problem with link to page [freeze flask]
Nuxt.js and Three.js production build - Cannot use import statement outside a module
Issue with Netlify Build Version
Error message: Gatsby-plugin-feed
My site has stopped being able to auto deploy... help
Assistance with deploying a vuejs app
Hugo BUILD failing due to outdated version
Deploys are failing all of a sudden
CSS isn't updating after deploy
Gatsby deploy rearranges my JSX
Need help debugging "Version '12.18.0' not found - try `nvm ls-remote` to browse available versions."
Build failing with gatsby-source-wordpress-experimental
Local NPM dependency in package.json not installing
Build fails due to missing module (SVG)
Gatsby build - failed Building production JavaScript and CSS bundles
Elm make needs to be updated to Elm 0.19.1
Netlify build started failing with no new commits/code changes
Publish + Swift: Deploy failed
Failed to minify the bundle. Error from Terser: Call retries were exceeded
Deploying failed with a hugo theme from github
Is there official discord server?
Command failed with exit code 129
Unable to deploy Hugo Academic Website via Git
Issue with deploying on Netlify UI
Build Failed with exit code 2
"Failed Build exceeded maximum allowed runtime" deploying default Gatsby-Ghost
[Support Guide] Compiled Build and Deploy Resources -- start here!
Build Fail with exit code 2
Next@12 failing to build sass on Netlify. Works on Vercel and locally
[Support Guide] Please help me troubleshoot. What information do I need to share?
Failed build for a website made with react & builder.io
Netlify and Astro 1.4.x: Styles not imported the same way as on local machine
Build command failed with exit code 1
Build problem: command failed with exit code 1
May you please help!
CSS looks wonky after deployment?
Builds failing without code changes. Same code runs on one Netlify site but not another starting Nov. 17
GatsbyJS deploy on netlify
Failed during stage 'building site': GraphQL Error
One codebase, two different deployment results?
Deploys successful but uploaded site is not found
Error app.netlify.com/access-control : 412
Netlify deploy: Error #85907 GRAPHQL
Replicate Netlify deployment build on local for Gatsby
Need help with fail stage building site
Issue with gulp while deploying in Netlify
Specifying node version isn't working
Failing build: Failed to build site
[Support Guide] How can I optimize my Netlify build time?
Cannot deploy react app, deploy fails
React Static build with hundreds of pages fails silently
Build script Build script returned non-zero exit code: 3
Deploy Error - failed to fetch cache
Jekyll build works locally but fails to build on netlify due to import error
Can you help me to debug this?
Need advice to troubleshoot this deployment
Can't edit the value of a DNS record of a domain managed by Netlify DNS
Help with site deployment
My hugo site lost some elements after deploy?
How does one debug a netlify build issue?