last updated by Netlify Support Dec 2022
Are you struggling to get your build working? Most build errors are caused by problems in code or data, and for those errors, our best guide / general starting place for debugging build troubles is this one:
But, sometimes your build is working fine and suddenly ends with some inscrutable errors that don’t seem to be “about” your code or site even. Perhaps you see an error message like this in your builds?
or, perhaps, your build is chugging along and suddenly ends with a “Killed” log message:
10:14:05 AM: /opt/build-bin/build: line 77: 1351 Killed [... details about the build]
These are both signs that your build attempted to allocate more memory than is available in our build system. This article describes the details of what is allocated to each build, for your reference. So what can you do if you’re seeing something like the above?
Improve your build performance.
We find that Gatsby is the site generator which primarily runs into this problem, though it is possible in any build pipeline. So if you do use Gatsby and see this, please start out by reading these two articles about improving Gatsby build performance:
Those articles have guidance on some pitfalls in commonly used Gatsby configs and suggestions for working around them.
Evaluate if you need to scale simultaneous builds.
Have a huge site and just need it to work? We do have a High Performance Builds, and we’ll be happy to connect you to our sales team for a discussion of pricing, which is custom for every use case and can scale to dozens of simultaneous builds with >4x the memory and 6x the CPU of our normal build environment.
Adjust how Node.js runs.
You can try to adjust how Node.js runs, specifically adjusting the stack size. Customers have had success with various different stack sizes, like the ones described in this stack overflow post. This may mean changing a build command like
npm run buildto ensure that its scripts, instead of running subprocesses like
gatsby buildinstead run something like:
node --max-old-space-size=4096 gatsby build, or alternatively (should have same result), set a
$NODE_OPTIONSenvironment variable to something like
You can try profiling your build to see what portion of it might overuse memory. One very relevant way to do this is using the instructions for running our build image locally and constraining the memory Docker has so you can figure out how much is needed and try to reduce. Within the docker image, you can use the workflow described in this article to actually do the profiling.
In case you run parallel workers to complete your build - consider not doing that, or constraining your CPU usage somehow. In our default build environment, there’s only 4 CPU’s available so running more parallel workers than that will just increase memory contention without increasing performance. You may find the guidance here helpful in case you use Gatsby: Resolving Out-of-Memory Issues | Gatsby
This advice won’t solve every problem but it has worked to solve most of the ones we’ve worked with. If this didn’t help you, please feel free to post a followup question describing the results of the experiments you attempted from the above list, so we can best advise you further.