[Support Guide] Frequently encountered problems during builds

Support Support Guides
1

Last reviewed by Netlify Support - October 2024

Overview

Sites on Netlify can be built using a variety of tools — different frameworks, programming languages and approaches. It can be incredibly frustrating to see your site fail to build! If you have a build on Netlify that is failing with an error message that you don’t understand, you are not alone. Here you’ll find some common build failure messages, and probable solutions to their causes. If you’re looking for more general information on build debugging, or interested in details about how our builds work, these other articles are probably a better starting place:

In case your problem isn’t seen here, or you don’t understand our suggested repair, or you otherwise need help - please don’t hesitate to post a new topic with a link to your build logs so this community can take a look and point our collective intelligence at your situation :slight_smile:

Before you begin: switch on debug mode

Do you know Netlify has a special environment variable you can set to get more information about your build? It’s simple to do and may help. Don’t forget to switch it off after you have found the problem, as it does slow down your build and may use up more build minutes!

In the Netlify UI,(not the netlify.toml) set the environment variable NETLIFY_BUILD_DEBUG to true to print additional debugging information in the build logs. The output does not contain sensitive information. To disable debugging, delete the variable. Alternatively, delete everything in the variable’s Value field.

For more information, give this a read through.

1. First steps - ruling out the obvious

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 the ones you use in your own development environment. You can find the settings for these in our Build Settings doc. That’s the leading cause of build failures.

1.5 Build logs

If you aren’t familiar with Netlify’s build logs, please check out this post before reading further. Many of the issues below reference messages you’ll find in our build logs.

2. Command not found - we need to know what your environment needs

One commonly observed issue with builds is failure with a message in the pattern of jekyll: command not found or gulp: command not found.

This means that the software required for that command you’ve set our build to use hasn’t been installed in our build environment.

We have very few programs installed by default, so you must specify installation of the software you need by including the proper configuration file, like a Gemfile for Ruby programs like jekyll, or package.json for Node.js 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 build system ONLY 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. If you’re using a monorepo, please see our advanced monorepo configuration options here.

3. Case sensitivity - not all filenames are treated the same way

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

It can be challenging to effectively change case of a file stored in Git from your case insensitive local environment. This article on StackOverflow describes a good workflow, as simply renaming and committing will almost certainly not have the desired effect.

4. Large files or sites can cause issues

Specifically:

  • Files over ~20 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 consider using Git Large File Storage (LFS) directly with your Git provider, or if that doesn’t appeal, host large content elsewhere (e.g. YouTube embedded videos). It’s also a good idea to confirm that you aren’t accidentally adding big files you don’t need.
  • 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 and they are all “new” to our CDN by checksum. Check out this article that has more details about what we consider changed/new content for some advice on how to avoid this pattern in your code, and get lightning fast uploads and better site performance for your visitors.

5. Don’t call me “build”!

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 with non-obvious errors, but certain failure!

6. Missing node packages that are located in package.json

So you have gulp mentioned in package.json, but still get gulp: command not found when you try to build with it? One potential cause is that when you set the NODE_ENV environment variable 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. So - watch out for that difference vs NODE_ENV=development (our default)

7. 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 four retries it still hasn’t worked:

3:25:03 PM: Starting post processing
3:25:27 PM: Starting post processing
3:26:54 PM: Starting post processing
3:31:15 PM: Starting post processing
3:41:46 PM: Starting post processing

…we fail that deploy. You’ll probably need to create a new topic here in community if this is the case to get more details about the error, unless you want to follow the next piece of advice.

Since the failure is in the asset optimization portion of the build, 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 review your CSS as there is likely an incorrect reference causing the behavior. Or, you could disable CSS bundling and minification to work around this.

Note that 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.

8. Build fails with Error 128

This error code usually means that there was some problem in cloning your repository.

In 99% of cases, it means 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 (or that it was never linked correctly).

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 > Repository , select Manage repository , 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 (see #9 below) - you need only ONE of those per repo!

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

In the other 1% of the cases, there is some OTHER problem cloning your repo - perhaps around Git LFS, Large Media, or some other git-related situation, and in those cases our Support team will have to look in our internal logs to debug things. We’ll still need a link to your deploy logs to do so.

9. Multiple builds

So you’ve noticed that every time you git commit, you get multiple builds when you were only expecting one. What gives?

This can happen if you have multiple copies of our webhook in your settings at your git provider, when you need only one. You’ll need to visit your git provider to check out your webhooks. Follow these URL patterns to find your settings:

GitHub: https://github.com/LOGIN/PROJECTNAME/settings/hooks

GitLab: https://gitlab.com/LOGIN/PROJECTNAME/settings/integrations

Bitbucket: https://bitbucket.org/LOGIN/PROJECTNAME/admin/addon/admin/bitbucket-webhooks/bb-webhooks-repo-admin

10. 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 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” button on the header of a failed deploy logs page, and then clicking the “Clear cache and retry ” option.

11. Yarn

If you use our legacy Ubuntu 14.04 Trusty or Ubuntu Xenial 16.04 build image (see also this article for details about a recent launch of a newer version, and you have a /yarn.lock file, Netlify builds set the --ignore-optional flag is passed to 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.

Note that if you do not have a /yarn.lock file, our build system will not install yarn and it will be unavailable in your deploy; you’d need to have it listed in package.json for npm to install in that case, before you can run it.

12. Gatsby and Environment Variables

Don’t forget that Gatsby is special in its treatment of Build 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 at browse time that you name following the pattern $GATSBY_VARIABLENAME in your JavaScript as described here: https://www.gatsbyjs.com/docs/environment-variables/

13. Hugo

If you are getting an error 255 status when building a Hugo website, try setting a HUGO_VERSION environment specifying he 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’ll need to make sure you are using our newer Xenial build image as described in this blog post. In that environment we use hugo 0.53 extended by default.

14. Bitbucket and Pull Requests

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. We do not anticipate that bitbucket will change things here since the open bug is over 6 years old. GitLab and GitHub work perfectly for PR’s and deploy previews!

15. Deploys seem to fail the first time they build; clearing cache and redeploying works - why?

Here are some potential root causes - check to see if any apply to your build.

16. Build times out

Sometimes a background process lingers after the build script exits, causing your build to time out and fail. For example, you might see something like this, with a long pause between log lines:

3:34:15 PM: Started saving pip cache
3:38:01 PM: Execution timed out after 15m0s

To see what the build is “still” doing in the background, you can add && ps auxw; false to the end of the build command, as described in this post.

Another cause of build timeouts is excessive logging. Check out this post for what to do if your build logs simply cut off.

Wrapping it up

This isn’t a list of every build failure possible, but it does address at least 90% of build problems we see. If this hasn’t worked in debugging your build, try posting a question in the Support Category and we’ll get you some advice!

4 Likes
3

It would be useful if your FAQ above included the following information:

The final part of the build after it gives the number of files to upload can time out without completing if you have many tens of thousands of files. However, some of the files (typically a few tens of thousands) will have been processed, so if you re-run the same build you fill find that there are now fewer files to upload. Repeating build re-runs will eventually get all your files uploaded and the build will complete.

However, there is a second “uploading” stage after the build has completed that can easily take several hours for the first deployment for a site with many tens of thousands of files. Once that deployment has completed, subsequent deployments (both build and subsequent upload stage) should be fairly fast (a few minutes) so long as there aren’t too many unchanged files.

1 Like
19

A post was split to a new topic: Build failed despute sucess with netlify dev

22

Last reviewed in August 2021.

24

Hi,
I have a Gatsby site deployed on Netlify but I am running into an issue with my latest deploy. After reading the above & Netlify’s docs, I believe I am encountering #7 - post processing issue.
The fail message says: ‘Deploy processing failed after 5 attempts.’

I have tried the following:

  1. Added CI='' npm run build as build command to bypass warning errors
  2. Disabled Asset optimization
  3. Downloaded Netlify CLI and ran netlify dev, netlify build (both successful)
  4. Ran DEBUG=* netlify deploy and am seeing: “error_message”: “Deploy processing failed after 5 attempts”.

Can you please advise on next steps to debug this issue? I have not been able to deploy my site since yesterday.

Thanks!

25

Hi @hyped1,

Are you using Netlify Forms? If yes, could you share the form’s code?

26

Hi @hrishikesh, I am using Netlify forms and have multiple forms on one page. I realized the deploy is successful when I only have one form.
I am setting each form name, id, and fields dynamically (using GraphQL, Gatsby, Contenful). Here is my form’s code:

<form
name={form.title}
method="POST"
data-netlify="true"
id={form.slug}
>
<div
  className="input_padding_bottom  mt-36"
  data-delay="100"
>
  <input
    name={form.formField1}
    type="text"
    id={form.formField1}
    size="30"
    placeholder={form.formField1}
    required
  />
  <label
    className="input_label"
    htmlFor={form.formField1}
  ></label>
</div>

<div
  className="input_padding_bottom "
  data-delay="150"
>
  <input
    name={form.formField2}
    type="text"
    id={form.formField2}
    size="30"
    placeholder={form.formField2}
    required
  />
  <label
    className="input_label"
    htmlFor={form.formField2}
  ></label>
</div>
<div
  className="input_padding_bottom "
  data-delay="150"
>
  <input
    name={form.formField3}
    type="text"
    id={form.formField3}
    size="30"
    placeholder={form.formField3}
    required
  />
  <label
    className="input_label"
    htmlFor={form.formField3}
  ></label>
</div>
<div className="" data-delay="100">
  <textarea
    name={form.formField4}
    cols="40"
    rows="4"
    id={form.formField4}
    placeholder={form.formField4}
  ></textarea>
  <label
    className="input_label slow"
    htmlFor={form.formField4}
  ></label>
</div>
<button
type="submit"
className="send_message"
id="submit"
>
{form.cta}
</button>
</form>
27

Well this piece of code looks fine. I believe the error would appear due to the fields being filled up dynamically.

In general this might happen when your attribute value contains '. For example, id = "let's" is wrong, id = "let us" would do.

28

@hrishikesh that solved it! One of my fields had an apostrophe. Thank you for your help!

29

Hi, I have my frontend and backend in the same folder, but want to host them separately, with the frontend on netlify, I put /client in the build, so it goes into the client folder to build, but deployment has been failing. This is the site name unruffled-euclid-43cc20

30

hi dimola, this isn’t really super related to the thread, generally. can you start a new thread please and post a recent failing build log along with information on what you have already tried? thanks.

31

okay, thank you for your response, how do I start a thread sorry, couldn’t figure it out, so i came here

32

your view may look a bit different, but from the main forums page at answers.netlify.com please just select “new topic” and give us as much information as possible:

image
image1739×615 154 KB

33

okay, thank you very much

35

A post was split to a new topic: Unable to deploy nft-minting-app