× press ESC to close

Netlify builds, deploys, and hosts your front end.

Build Gotchas

While our build environment works for most build pipelines, there are a few special cases that we are aware will cause you some difficulty. Some related recommended reading on this topic is this blog post on how our build bots build your site. You should also consider whether you need to set any of the variables that can affect the build environment.

Below are some of the more common problems encountered with our build system:

  • Case sensitivity. If you develop on Windows or OSX, and your code includes something like jQuery/jquery.js - it will fail on our build system as the file system here is case sensitive while your build environment is not. The error messages that result may not clearly indicate this.
  • Large files or sites:
    • Files over 10 MByte in size are not well-supported by our CDN and will likely 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.
  • Don’t name your build command “build” or try to use the debug build steps to run a build locally in our build environment. This will fail and give you a strange looking build log.
  • Processing errors:
    • Redirects or Custom header rules that we can’t process at all are mentioned near the end of the build log for a deploy, but will NOT cause the build or deploy to fail.
    • There are some situations during build that may lead to a failure in postprocessing - many things that fail will lead to a retry which might work; 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 postprocessing 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.
  • 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 repo, after linking the repo to your site. We only have permission to create a copy of your code when you link the repo, so if you are seeing an “Error 128”, relinking your repo via our UI (choose “Edit” on the Build & Deploy Settings section about your repository) is a good first attempt to fix things.
    • 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 login 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. We’ll discard this cache if there are changes to some of your dependency listing files (e.g package.json or yarn.lock) or settings (e.g. Node.js version). You can check which directories are cached in our build image , but they are also listed below:
    • node_modules
    • .yarn_cache
    • .bundle
    • bower_components
    • 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 checking the “Clear build cache” option before clicking “Retry”:

Retry Failed Build

  • Yarn
    • 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.

Notice something is incorrect or outdated?

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

Want to get started quick?