[Support Guide] Frequently encountered problems during builds


Sites on Netlify can be built using many different tools — differing 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 the 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.

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


  • 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 our Large Media feature, 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: Log in with Atlassian account

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: Environment Variables | Gatsby

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!

[Support Guide] My site deploy fails unless Netlify's build cache is cleared
Next.js 9.3 and getServerSideProps not working
Gatsby build is not found
[Support Guide] Netlify app builds locally but fails on deploy (case sensitivity)
Error while building site
Build Error: GPG signature for this Yarn release is invalid!
Cant deploy my jekyll blog
Deploy details Deploy failed
Vue.js build fail
Site not building
Manual deploy - stuck at uploading
Build issue. npm ERR! code ELIFECYCLE
Falha na compilação devido a um erro do usuário: O script de compilação retornou código de saída diferente de zero: 2
Unable to build project from stackblitz
Stuck at "Waiting for other deploys from your team to complete"
Fresh Hugo deployment failed
Failing build react application with yarn
Error during Yarn install
Deploy Existing Jekyll Site to Netlify
Frozen-Flask_build.command failed
Dependencies installation error
Githup cant deploy website
Build error when linked to GitHub repo
Not able to find `gatsby-source-contentful` plugin at build
Deployment error build.command failed
Bought a domain, connected it, and now its saying "page not found"
I'm experiencing deploy failed
Stuck on 'Site deploy in progress'
Error: Build script returned non-zero exit code: 1
System error on deploy
Deploy website- images and font
[Error in deployment] public folder is not created for hugo
CSS not getting loaded on Netlify Deploys (Jekyll)
Unable to build, build failing
Unsupported platform for fsevents@2.3.2 error on deploying
[Support Guide] What can Netlify's staff help debug about my failing builds or deploys?
Can anyone please help? I'm new. Thank you!
Unable to get updates when deploying my website
Building production JavaScript and CSS bundles failed
Build error - yarn
Page Not Found, URL that doesn't exist on this site
Support Guides - Or, how to find answers for frequent questions!
Gatsby Wordpress CMS deploying build issue
Hugo Partial Not Rendering Once Deployed to Netlify
Unable to build migrated CRA app
When i try to deploy the application I am getting this error. it is showing build script returned non-zero code: 1
Deploy error: Module not found: Error: Can't resolve 'webpack' in '/opt/build/repo/node_modules/@next/react-refresh-utils'
My app builds and works fine locally but not on Netlify
Eleventy build command - is "npx @11ty/eleventy" correct?
'bash: yarn: command not found' error
'building site': Build script returned non-zero exit code: 1
Gatsby builds local, but fails on Netlify
NuxtJS deploy/building failing
Deploy from Github Debug about a "Gatsby build" hold up from forestry cms
Command failed with exit code 127: build staging
Deploy successfully but return a blank page with no errors in consle
Error in host an extended hugo site with config.yaml
Build timeout after 10 minutes
Failed during stage 'Reading and parsing configuration files'
404 after successful deployment
Site deploy still failing after several attempts
Not able to deploy a React site, fsevents warning
Gatsby build - failed Building production JavaScript and CSS bundles
Failed Building production JavaScript and CSS bundles ...[BABEL]
Deploy bug "build error" on each push
Page Not Found on deploy- Git Hub
Command failed with exit code 7: npm rebuild && gatsby build
React Component is not rendering after deploying to Netlify
Command failed with exit code 7: npm rebuild && gatsby build
Failed during stage building site: Build script returned non-zero exit code: 1
Failed during stage building site: Build script returned non-zero exit code: 1
Failed to load resource--which is React?
Sh: 1: webpack: not found for React deployment
Why is my site not updating changes
Command failed with exit code 1: gulp build
Building problems
The deployment engine ignores the build.publish setting from the netlify.toml file
Cannot find module './lib/ast-converter' (Error):
Error finding node_modules when building
Build failed despute sucess with netlify dev
Deploying site with Parcel initial build worked, subsequent builds fail
Problem when deploy node js project from GitHub repo CI= npm run build
Build failed when trying to download node.js version
Couldn't find package
Error while building | npm ERR! Error while executing: /usr/bin/git ls-remote -h -t ssh://git@github.com/angular/router.git
Error the core-js
"Error: No such directory" Did you forget › to run a build? after netlify deploy --prod
"build.command" failed. Command failed with exit code 1: parcel build index.html
Our netlify-cms app suddenly stopped building
Not able to deploy react app
Build script returning non-zero exit code: 2
[ React / Next.js ] You need to enable javascript to run this app
Deploy failed - Command failed with exit code 254
Eleventy "non-zero exit code: 127" Error
Netlify deploys the editor but not the preview
Netlify image issues
Deploy fail timed out
Need help Build Site error
[Support Guide] Compiled Build and Deploy Resources -- start here!
How to deploy simple express app from Github to Netlify
Help in deploy process
WebSite Deployment failed with error 2
TypeError during production
Build failed due to a user error: Build script returned non-zero exit code: 2!
Unable to deploy Eleventy site to Netlify
Help me about Failed during stage 'building site': Build script returned non-zero exit code: 1
Error Deploying a new version of my site
Build run command issues
Build failed with the error - TypeError: Cannot read properties of undefined (reading 'get')
Deploy issue Build command failed code 254
Command failed with exit code 254
Builds are suddenly failing with no change from me
"build.command" failed
Build.command error
"non-zero exit code: 2"
Error: Can't resolve '/opt/build/repo/node_modules/babel-preset-react-app/node_modules/@babel/runtime/helpers/esm/slicedToArray.js' in '/opt/build/repo/src/components'
Build Error: ENOTFOUND artifcatory-slc.oraclecorp.com
Gatsby 4 Build Issue Works Local but Fails on Netlify
Getting "Failed during stage 'building site': Build script returned non-zero exit code: 1" - works with netlify dev locally
Nft minting website build commads error I'm getting an error like this can anyone help?
Command failed with exit code 254: CI= npm run build (https://ntl.fyi/exit-code-254)
I am getting this build error Please help
Deploy failed due to Errors during building
Migrating a single page JS webapp to Netlify Functions for env secret token hider
Maximum Runtime exceeds [Next.js]
Deployment error with build
The site goes live but the screen is blank
Extend 15min max build time to 30min
I can't deploy my site non-zero exit code: 2
Error deploying react app
Deploy error error - npm ERR! enoent ENOENT: no such file or directory, open '/opt/build/repo/package.json'
React app not deploying due to missing dependencies
Bash: build: command not found
Error message : Command failed with exit code 255
Jekyll site won't build: Error: No such file or directory @ rb_sysopen
Jekyll site won't build: Error: No such file or directory @ rb_sysopen
Encounter Error Code 127 while deploying an ionic react app
Failed during stage 'building site': Build script returned non-zero exit code: 1
Build fails because it can't resolve an image that is there?
Yarn install , got errors
Delpoy directory build does not exist , Tailwind Css
Error when deploying to Netlify DNS via Netlify API
React App not showing on mobile
Error Deploying Angular App
Site does not update after file updates from Gitlab
Unable to Deploy A NextJS Application
Vue.js components cannot be found by Netlify - case sensitive
React-Build Script Failed to Compile
Command failed with exit code 127: npm run build (https://ntl.fyi/exit-code-127)
React App Build failed
Netlify problems with production
Build exceeded memory limits
"This site can’t be reached" . why is this happening to me?
Hugo build error 255 despite using latest versions
Command failed with exit code 1: CI='' npm run build
Gatsby error with useRef only when deploying
Command failed with exit code 1: CI= npm run build (https://ntl.fyi/exit-code-1)
Problem running Build command: npm run prerender
Failing to compile with exit code 1 & 2
Netlify build cache error
My react app won't deploy
Unable to load anything in Netlify Dashboard
ENOENT: no such file or directory, mkdir '/opt/build/repo/dist'
Netlify CLI - Waiting for framework port
Cannot build with pnpm
Build Fails Next JS 13 (Not using experimental app directory)
Build Failure with Gatsby
Build intermittently fails to prepare repo (timeout, exit status 128)
Hugo Partial Not Rendering Once Deployed to Netlify
RollupError: Could not resolve "./navbars/Topbar.jsx" from "src/components/Tattoos.jsx"
Continous Deployment & Deployment via the UI Not Working
Exit code 128 during build failed
Intermittent failed deploys. Builds fine sometimes, and errors with exit code 2 other times
Deploy failed - header.css - the relative module was not found - case sensitive
Context.identity null in localhost
Can't Deploy to code sandbox through netlify
Webflow cms is not working On Netlify
Unable to get updates when deploying my website
Issue im having with NPM
Command failed with exit code 127: nmp run build
Blank page showing up for Next.js deployment
Deply Failing: Yarn Build Command Not Working
Nuxt JS Static Sites all failing to build on npm run generate
Deployment failing due to webpack-cli issue
Deploying a web page to netlify using parcel
Please help! Trying to deploy a site using Next.JS!
Problems with deploy
Deployment Issue: NPM dependency 404s (Vanilla JS site)
Vue Build Failed
Hey, i have a problem in deployment of my todo app
React deploy fail
How to make user friendly build error messages?
Problems with deployment - autoprefixer
Deploy killed after 5 minutes
Failed during stage 'building site': Deploy directory '_site' does not exist
Deploy directory 'target' does not exist
Deploy failed with message this relative module was not found
Deploy fails because of incompatible module
Constant and frustrating build issues with LFS
How to get Netlify to use yarn if there is no yarn.lock file?
Deploy Error - failed to fetch cache
Failing deploy with build error 1
Gatsby React App deploy failed from git
Gatsby build fails in Netlify after "run page queries", no errors shown
Missing hugo pages
Issue building website from plasmic.app to netlify
Maven, issue with non-zero code: 127, maven command not recognised, configuration file present
Unable to build migrated CRA app

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

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

Last reviewed in August 2021.

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.


Hi @hyped1,

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

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:

  className="input_padding_bottom  mt-36"

  className="input_padding_bottom "
  className="input_padding_bottom "
<div className="" data-delay="100">
    className="input_label slow"

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.

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

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

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.

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

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:

okay, thank you very much

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