[Common Issue] Debugging site builds


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 yours. There are other reasons as well, which you can read more about here, in our article on other “frequently encountered build problems”, but the version mismatch is the probable reason for problems. This article describes all the possible 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/javascript, you should make sure that we build using the same versions of Node , npm , and the same Node Environment settings that you do locally. Take a look at this article with instructions on how to check which versions of node and npm you have installed on your local machine.

Our current default versions are:

  • Node v 10.13.0 (currently - we track Node.js 10 LTS latest)
  • NPM v v6.4.1 (default with that version of Node) and Yarn version 1.3.2
  • a NODE_ENV setting of development

(These are subject to upgrades at any time, but are valid as of February 2019)

If you don’t mean to use the package manager yarn but wish to use npm instead - you won’t have a /yarn.lock file in your repository since that is what causes us to use yarn automatically. If you mean to use yarn and DON’T have a /yarn.lock in your repository, you’ll probably want to at the very least make sure that yarn is in your /package.json so we install it for you before you try to use it :slight_smile: .

You can adjust those versions as follows:

  • You can 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 6.11.2). You can also use a /.nvmrc file with this number in it.
  • you can set the npm version by setting an NPM_VERSION Build Environment variable, and similarly a YARN_VERSION variable will work for setting a yarn version.
  • you can set the NODE_ENV by setting a Build Environment Variable by that name.

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 follow these steps:

# 1. clone a new copy of your repo,
# 2. then replace the placeholders in the export line below with any variables you have set in our admin UI
# then run the below commands
docker pull netlify/build
git clone https://github.com/netlify/build-image
cd build-image
./test-tools/start-image.sh /path/to/your/checked/out/repository
# remember to replace these with your real variables, if any!
export VAR1=val1 VAR2=val2 
# use your real build command of course - maybe `npm run build` or `hugo` ?
build whatever_your_build_command_is 

In case that still doesn’t help, don’t give up! Please respond to this thread with the information you gathered while debugging, including this information:

  • 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.
1 Like
[Common Issue]: Frequently encountered problems during builds
[Common Issue] How do I access private repositories in the build environment?
Build success on local but fail on netlify
pinned #2