Join us at JAMstack Conf San Francisco, October 16-18. Register today

Build Gotchas

This article describes how to debug failing builds in Netlify’s build service.

In case your build fails on Netlify, first make sure it builds locally in your own development environment. This is a prerequisite to all of the below suggestions.

If your build works locally, the next debugging step is to ensure the package versions we use to build match yours. You can find the settings for these in the Build Settings doc. That’s the leading cause of build failure.

Once you’ve considered the most frequently encountered issues listed below, there is some additional reading linked at the bottom of this article which may help you debug in more depth or find answers to less commonly asked questions.

Command not found

If your build fails with jekyll: command not found or gulp: command not found or anything in that pattern, it means that the software required for that command hasn’t been installed in your build. You can tell the buildbot to install the software you need by including the proper configuration file, like a Gemfile for Ruby programs like jekyll, or package.json for Node programs like gulp.

Check out the Build Settings doc for more details on how to tell us to install your toolchain. Once we find your configuration file in the root of your repository, we’ll automatically use it before trying to run your build command.

Note that by default the buildbot looks for the configuration file in the root of your repository. If your configuration file is located in a subdirectory, you will need to change your folder structure or specify the directory to change to before starting the build. You can do this by adding a netlify.toml with a base property or by going to Settings > Build & deploy > Continuous Deployment > Build settings and entering a base directory.

Case sensitivity

If you develop on Windows or OSX, and your code includes something like jQuery/jquery.js — the Netlify build may fail as the file system used in Netlify builds is case sensitive while your build environment is not. The error messages that result may not clearly indicate this!

To effectively change case of a file stored in Git from your case insensitive local environment, it may be necessary to git mv or git rm and then add the file again, as simply renaming and committing will not have the desired effect.

Large files or sites

  • Files over 10 MBytes in size are not well-supported by our CDN and may fail to upload to our system, causing your entire deploy to fail. You should host large content elsewhere (e.g. YouTube embedded videos).
  • Sites with tens of thousands of html files can lead to long processing times. This shouldn’t cause the deploy to fail, but even a “quick” manual deploy can take quite awhile (many minutes) to finish if you have tens of thousands of files.

Build command

Don’t name your build command build or try to use the debug build steps to run a build locally in our production build environment. This will fail and give you a strange looking build log.


If you manually set the NODE_ENV to production, any devDependencies in your package.json will NOT be installed when we automatically run yarn install or npm install at the beginning of the build.

Post processing

There are some situations during build that may lead to a failure in post processing — many things that fail will lead to a retry; if after 4 retries it still hasn’t worked, we fail the deploy. You’ll probably need to contact support in this case to get more details about the error, unless you want to follow the next bullet point’s advice.

You may try disabling asset optimization if your site fails deploy during post processing and/or some of your assets end up with nonsense paths on the portion of our CDN hosted on Cloudfront. For instance, if you find an incorrect Cloudfront URL with a {$rootfolder} component in it, you’ll need to disable CSS bundling and minification to work around this, or review your CSS as there is likely an incorrect reference causing the behavior.

Redirects or Custom header rules that we can’t process at all are mentioned near the end of the build log and in the Deploy Summary for a deploy, but will not cause the build or deploy to fail.

Build fails with Error 128

Typically this means that we don’t have permission to clone the repository you are trying to deploy. The usual cause for this is that someone made some changes to settings for the parent organization, or repository, some time after linking the repository to your site.

We only have permission to create a copy of your code when you link the repository. So, if you are seeing an Error 128, relinking your repo via our UI is a good first attempt to fix things (go to Settings > Build & deploy > Continuous deployment > Build settings, select Edit settings, then Link to a different repository). If you do this, please check your WebHook settings at your Git provider to be sure you don’t have any duplicate Netlify webhooks.

Note: Your GitHub, Bitbucket, or GitLab user account may not have the privilege level required to link the repo to Netlify, even if you can log in and access it from the the Git host’s website. You generally need administrative privileges on the repository and/or owning organization. Related: documentation about Netlify & GitHub permissions

Build cache

We cache certain directories (typically — ones that contain dependencies that we installed for your build) at the end of a successful build, to make future builds faster. Changes to those files — for instance package.json, yarn.lock, Gemfile.lock — will cause us to re-run the installation command which may update cached dependencies if needed. It isn’t guaranteed a change will take place if the previous dependencies still satisfy the installer, though! You can check which directories are cached by looking for $NETLIFY_CACHE_DIR in the file for your site’s selected build image.

If a build fails, it’s worth retrying with a cleared build cache to see if this works better. You can do this by clicking the “Retry deploy” button on the header of a failed deploy logs page, and then clicking the “Clear cache and deploy site” option:

Deploy failed, retry with cleared cache


If you have a /yarn.lock file, --ignore-optional is passed in to the yarn install by default. You can’t unset this, but you can override it by adding --no-ignore-optional to your YARN_FLAGS build environment variable.

If you do not have a /yarn.lock file, our buildbot will not install yarn and it will be unavailable in your deploy.


Don’t forget that Gatsby is special in its treatment of environment variables — whether set via netlify.toml or via our UI. You can access these variables during build via the normal variable handling in your build pipeline when creating your site from source code, but can also directly access variables that you name following the pattern $GATSBY_VARIABLENAME in your JavaScript at browse time as described here:


If you are getting an error 255 when building a Hugo website, try setting HUGO_VERSION to the version you are using locally. This will set the Hugo version that our buildbot uses to build your site.

If you would like to use the new Sass compilation features in recent Hugo releases (using the “extended” version of the binaries), you can use the new build image selection setting (currently in beta) to select the Ubuntu Xenial 16.04 image, which supports all Hugo versions.


Due to limitations with Bitbucket’s API, we do not build deploy previews for pull requests on Bitbucket repositories. This is specifically due to the the fact that they do not send complete refs in their webhooks for pull requests. Bitbucket has an open issue about this.

More resources

While our build environment works for most build pipelines, there are a few special cases that may cause you some difficulty. To get more context on how our builds work, check out this blog post on how our build bots build your site.

If your issue doesn’t seem to be addressed above, you can visit the Deploying and Building category in our Community forum to browse posts about common issues or start a new discussion. Many questions about specific build scenarios have also been asked and answered on StackOverflow.

Notice something is incorrect or outdated?

First off, great catch! We appreciate your discovery and want to ensure it gets addressed immediately. Please let us know here.

Want to have a conversation?

Visit the Netlify Community to discuss ideas and questions with your fellow Netlify users.

Want to get started quick?