Fix “Build exceeded maximum allowed runtime” on Netlify

Build exceeded maximum allowed runtime

Netlify prints this line at the end of a deploy log when it has stopped a build for running too long. Often nothing above it looks wrong. The framework says the build is done and the output folder is ready. Then the log goes quiet until the timeout hits.

There are two very different ways to hit this limit. Either the build is still doing real work when time runs out, or the work finished and something it started never exited. The fix for one does nothing for the other, so the first job is to work out which one you have.

What “maximum allowed runtime” means on Netlify

Builds on Netlify are a metered resource, and every site has a build time limit. Netlify’s support guide on the build time limit gives the default: 15 minutes for the build, plus 5 more minutes for any post-processing the build system does. The setting is stored per site as build_timelimit, in seconds. A value of null means the default of 900 seconds applies. Once a build goes past the limit, Netlify stops it and fails the deploy with this message.

The limit is there so a build that hangs can’t burn through your build minutes. Without it, one stuck build could run for hours and use up your whole monthly allowance.

Two details explain most of the confusion around this error:

• Netlify waits for every process, including ones your build command didn’t start directly. The Hung or stuck build guide says the build environment requires all processes to complete. If your framework exits with the right code but leaves a child process running, the build doesn’t end.
• The build machine may be smaller than your laptop. Netlify’s guide on how long builds should take says a build is guaranteed only 4 CPUs and 8 GiB of memory, and may compete for resources when the build network is busy. A build that takes 12 minutes on your machine can cross 15 minutes on Netlify.

Build command: Default build_timelimit, 900 s

Post-processing: Extra time for deploy processing

Finished or still working: reading your deploy log

Open the failed deploy and look at the last lines of real output before the error, along with their timestamps.

• A long silence after a success message. If your framework printed its done line and nothing new appeared until the error, the build finished and something kept running. That is cause 1 below.
• Steady progress right up to the cut-off. If pages, images or bundles were still being logged when the error appeared, the build was still working. That is cause 2.
• The build command finished and the log moved on to deploying or processing files. That points to post-processing a very large deploy, which is cause 3.

Then reproduce the build on your own machine. Netlify’s build troubleshooting tips say a build has to work locally before anything else, and that differences in package versions are the leading cause of failed builds. Time your build command and watch whether you get your shell prompt back:

time npm run build

If the output stops but the prompt never comes back, something is still running. That matches what happens on Netlify. You can also build locally with the Netlify CLI:

npm install -g netlify-cli
netlify build

graph TB A[Build exceeded maximum allowed runtime] --> B{Log silent after done message?} B -->|yes| C[A process never exited] C --> D[List processes with ps auxw] B -->|no| E{Build command finished?} E -->|yes| F[Slow processing of many files] E -->|no| G[Build needs over 15 minutes] G --> H[Speed it up or raise build_timelimit] F --> I[Change fewer files per deploy] style C fill:#fee2e2,stroke:#fca5a5,color:#7f1d1d style G fill:#fee2e2,stroke:#fca5a5,color:#7f1d1d style D fill:#d1fae5,stroke:#6ee7b7,color:#065f46 style H fill:#d1fae5,stroke:#6ee7b7,color:#065f46

Cause 1: a process that never exits after the build

This is the most common cause, and raising the limit doesn’t fix it. A hung build waits until any limit runs out, so a higher limit only means it burns more minutes before failing.

Netlify’s hung build guide names two culprits: a watch command that checks for file changes, which is useful in development but has no place in a production build, and background child processes. Other things to check are a server started by a script, and code that runs during static generation. The Node.js timers docs say the event loop keeps running as long as a setTimeout or setInterval timer is active, so an interval that is never cleared keeps the process alive after the last page is written. Open connections to a database are worth checking too.

Confirming a lingering process

1. Change the build command so it lists every running process once the build finishes, then fails on purpose. Netlify’s guide suggests adding && ps auxw ; false to the end of your command. In netlify.toml the line looks like this:

[build]
  command = "npm run build && ps auxw ; false"

2. Push and open the deploy log. Once your build finishes, you will see a process table. Look past the shell and your build command for anything that shouldn’t still be running, such as a dev server, a file watcher, a database client or a worker pool.
3. Treat this deploy as a diagnostic only. Read the listing, then move on to the fix.

Stopping it

1. Remove development-only commands from the build. If your build script chains a watcher or starts a server, split it out. Keep a separate dev script for those.
2. Close what your build-time code opens. If a data-loading step connects to a database or opens a socket, close it once the data is fetched:

const client = await connect(process.env.DATABASE_URL);
try {
  const pages = await client.query('select slug, body from pages');
  await writePages(pages);
} finally {
  await client.end();
}

3. Keep browser-only code out of static generation. Generators that render components at build time also run the timers inside them. Guard intervals and other client-only work so they only run in the browser:

if (typeof window !== 'undefined') {
  const id = setInterval(refresh, 5000);
  // clear it when the component unmounts
}

4. Take the diagnostic out again. Put the build command back to normal without ps auxw ; false, push, and check that the deploy log moves straight from your framework’s done line to the deploy step.

Cause 2: the build needs more than 15 minutes

Some builds are not stuck at all. Netlify’s guide gives the typical cases: many thousands of HTML, CSS and JavaScript files to process, or build-time transformations of thousands of images. You can tell this is your case when the log shows steady progress until it is cut off and your local build takes close to 15 minutes or more. The guide on build duration adds that a site that builds slowly locally will also build slowly on Netlify.

Make the build faster

Netlify’s guide on optimising build time and the troubleshooting docs list these changes:

1. Keep the dependency cache warm. Netlify caches npm and Yarn modules between builds. Any change to package.json or the lockfile reruns the install, though it still uses the cache to some degree. The troubleshooting tips suggest retrying a failed build with a cleared cache, using Retry without cache, to check whether that works better.
2. Don’t install what the build doesn’t need. Some packages take a long time to install. Set the NODE_ENV environment variable to production and move test-only tools into devDependencies.
3. Configure plugins with care. Some generator plugins use a lot of memory and run slowly, and the guide notes they can cause builds to fail with a timeout. Check which plugin’s step takes the longest in your log.
4. Stop building commits that don’t need it. Put [skip ci] or [skip netlify] in a commit message to skip that build. Limit which branches build under Branches and deploy contexts, or add an ignore command in netlify.toml, which file-based configuration runs as a Bash or Node.js command to decide whether to rebuild:

[build]
  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF -- site/"

Raise the site’s build_timelimit

Netlify’s dashboard has no setting for the limit. You change it through the API, and the Netlify CLI is the easiest way to call it. These are the steps from Netlify’s support guide:

1. Install the CLI, sign in, and check that you are authenticated:

netlify login
netlify status

2. Find the Site ID under Site settings > General > Site details, then read the current value:

netlify api getSite --data '{ "site_id": "YOUR_SITE_ID" }' | jq '.build_timelimit'

If you get null, the 900-second default applies.

3. Set a new limit in seconds:

netlify api updateSite --data '{ "site_id": "YOUR_SITE_ID", "body": { "build_timelimit": 1800 } }'

4. Run the getSite command again. It should print 1800. Then trigger a new deploy.

You can set up to 1800 seconds (30 minutes) yourself through the API. A larger value returns JSONHTTPError: Unprocessable Entity. The guide says Netlify’s support team can set longer limits, so open a support request with your Site ID if 30 minutes isn’t enough. An Unauthorized response means you aren’t signed in or your API key is wrong.

Build somewhere else and deploy the output

Manual deploys have no build time limit because they have no build step. The build duration guide says their time depends mostly on the total size and number of files. If your build needs more time than Netlify allows, run it in another CI system and upload the result with the CLI:

npm run build
netlify deploy --prod --dir=dist

The build configuration overview covers this setup. You stop builds on Netlify, build with the CLI elsewhere, and publish manual deploys with the CLI or API.

Cause 3: post-processing a very large deploy

The build command can finish on time and the deploy can still take a long while afterwards. Netlify’s troubleshooting docs say sites with tens of thousands of HTML files can take many minutes to process, and that this shouldn’t cause the deploy to fail on its own. They also say files over 10 MB are not well supported by the CDN and may fail to upload. The build duration guide says the time for processing and uploading is added on top and doesn’t need to complete within the initial 15 minutes. So if the error appears while files are processing, check for a lingering process as well.

Either way, a deploy that changes fewer files gets through processing faster. Netlify’s optimisation guide points out that every changed file has to be stored after the build. A build that renames or rewrites unrelated files every time is slower to deploy than one that changes only what it needs to. Host very large media elsewhere.

Keeping builds under Netlify’s limit

Once the build passes, add a check so the next regression fails fast in your own CI, before Netlify stops it:

- name: Build must finish and exit within the Netlify limit
  run: timeout 900 npm run build

The aim is for the job to fail if the build is still running after 900 seconds, which would catch a slow build and a hung process the same way. Check how timeout behaves on your CI runner before you rely on it. If you have raised build_timelimit, set the check a little below the new value so you see a warning before you reach the limit.

Three habits help too:

• Watch the trend. Look at build durations on the team’s Builds page every so often. Builds rarely jump from 5 minutes to 16 in one commit. They creep up as content and dependencies grow.
• Keep the build command for building only. Watchers, servers and anything long-running belong in the dev script.
• Only raise the limit once you know the build isn’t hung. Run the ps auxw check first. A higher limit on a hung build only makes each failure use more build minutes.

See Polylane as your AI SRE.