Fix Netlify “Command did not finish within the time limit”

Command did not finish within the time limit

The deploy log has been running for a long time, and then it ends with something like Failed during stage 'building site': Command did not finish within the time limit followed by Failing build: Failed to build site. Sometimes the build looked fine right up to that point, and the log even printed the Netlify Build Complete box. Sometimes it went quiet for many minutes first. Either way, no new deploy goes out.

The message comes from Netlify’s build system. It means the clock on your build ran out before every process the build started had exited. It doesn’t say why. That is the part you have to work out, because the fix for a stuck build and the fix for a slow build are different.

What “did not finish within the time limit” means on Netlify

Every Netlify site has a build time limit. Netlify’s support guide on the build time limit says the default for all sites is 15 minutes, plus 5 extra minutes for any post-processing the build system does. Builds use metered build minutes, so the limit stops a stuck build from running for hours and using them all up. When a build goes over, Netlify stops it and fails the deploy with this message.

The key detail is what counts as “finished”. Netlify’s guide on hung or stuck builds says the build environment waits for all processes to complete, including the background ones your build started. Your main command can exit with code 0 and the build still never ends, because some child process is still alive.

These two lines come from one failing build posted on the Netlify forums:

10:43:42 PM: Execution timed out after 17m59.952029417s
Failed during stage 'building site': Command did not finish within the time limit

The duration on the Execution timed out after line tells you roughly how long the build ran before Netlify stopped it. It won’t always read 15 minutes, because Netlify support can change the limit per site.

Telling a stuck build from a slow one

Open the failed deploy in the Netlify UI and read the timestamps. Three patterns cover almost every case:

1. The Netlify Build Complete box appears, then the timeout. Your build command finished, but something it started is still running. That is a leftover process.
2. A long gap with no output, then the timeout. A step stopped making progress, or it started a process that never returns. Look at the last line before the gap: that step is your suspect.
3. Steady output right up to the timeout. The build is doing real work and simply needs more time than the limit allows.

graph TB A[Build fails at the time limit] --> B{Build Complete box in log?} B -->|yes| C[A process outlived the build] B -->|no| D{Log silent for many minutes?} D -->|yes| E[A step hung mid build] D -->|no| F[Build is slow but working] C --> G[Find it with ps auxw and stop it] E --> G F --> H[Speed up the build or raise the limit] style C fill:#fee2e2,stroke:#fca5a5,color:#7f1d1d style E fill:#fee2e2,stroke:#fca5a5,color:#7f1d1d style G fill:#d1fae5,stroke:#6ee7b7,color:#065f46 style H fill:#d1fae5,stroke:#6ee7b7,color:#065f46

Pattern matters before you touch the limit. If a process never exits, a longer limit only makes the build fail later and use more build minutes.

Cause 1: a process keeps running after the build

This is the case Netlify’s support guides return to most often. The guide on how long builds should take puts it plainly: some builds really do run for more than 15 minutes, but most time limit failures turn out to be a started server, or a framework that left processes running.

How to tell it’s yours: the log shows your framework’s success line, or the Netlify Build Complete box, and then nothing until the timeout. The build finishes locally, but the terminal doesn’t give you the prompt back, or it takes a long time to return.

The usual culprits:

• A watch command. The hung build guide names this one: a watcher that checks for file changes is useful in development and never exits on its own.
• A server started by the build command. For example, a build script that runs npm start or a preview server to prerender pages and never shuts it down.
• Child workers left behind by a framework. The same guide links Gatsby issues where gatsby build left a dangling jest-worker child process.
• Open handles in your own scripts. A data-fetching or seeding script that opens a database or socket connection and never closes it keeps Node alive after its work is done.

Fix: find the process and make it exit

1. Reproduce locally. Run the exact build command and check it hands back your prompt:

   npm run build; echo "exit code: $?"

   If the exit code prints only after a long wait, or never prints, the problem is in your code and you can debug it on your machine.
2. If it only hangs on Netlify, list the running processes at the end of the build. Netlify’s hung build guide suggests appending && ps auxw ; false to your build command. In netlify.toml:

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

   The trailing false fails the build on purpose, so this run never deploys. Read the process list in the log, look for anything that isn’t part of the build image (a node server, a watcher, a worker pool), and then remove the debug suffix.
3. Stop the build from starting that process. Change --watch or dev scripts to their one-shot build variants. If a script must start a server, shut it down before the script ends.
4. Close what your own scripts open. Call your database client’s close or end method once the work is done, and make sure the script exits:

   async function main() {
     const rows = await db.query("select * from products");
     await writePages(rows);
   }
   
   main()
     .then(() => db.end())
     .then(() => process.exit(0))
     .catch((err) => {
       console.error(err);
       process.exit(1);
     });

5. Redeploy and check that the log goes from the build output straight into the deploy steps.

Cause 2: the build has outgrown the limit

How to tell it’s yours: the log keeps printing progress until the timeout. Builds that used to pass have been getting slower as you add pages, products or images, and now one has tipped over the limit. Netlify’s guide on the build time limit lists the typical reasons: many thousands of HTML, CSS and JavaScript files to process, or transforming thousands of images at build time.

Fix: make the build do less

Netlify’s build optimisation guide gives the levers that apply here:

1. Keep the dependency cache warm. Netlify caches your npm, yarn and gem dependencies between builds. A change to package.json, yarn.lock or Gemfile.lock triggers a fresh install, and clearing the cache forces a full reinstall. Use a cleared cache when you are debugging, but don’t make it your default.
2. Drop heavy dependencies the build doesn’t need. The guide gives Cypress as an example of a package that takes a long time to install. Move test-only packages to devDependencies and set NODE_ENV to production so the install skips them:

   [build.environment]
     NODE_ENV = "production"

   Check first: if your bundler or framework sits in devDependencies, this setting removes it and breaks the build. Move only the packages the build never runs.
3. Configure your generator for production. The guide notes that some static site generator plugins use a lot of memory and run slowly, enough to cause a timeout. Image processing plugins are the usual offenders. Cache processed images, process fewer sizes, or move image work to request time.
4. Change fewer files per deploy. Every changed file has to be stored after the build. Netlify’s build troubleshooting tips note that sites with tens of thousands of HTML files can have long processing times. Stable file names make each deploy smaller.

Fix: raise the build time limit

When the build is doing useful work and you can’t make it fast enough, raise the limit. The setting is build_timelimit on the site, in seconds. Netlify’s guide says it isn’t in the web UI, so you change it through the API, most easily with the Netlify CLI.

1. Install the CLI and log in, then confirm with netlify status.
2. Find your Site ID under Site settings > General > Site details.
3. Read the current value. null means the default of 900 seconds applies:

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

   null

4. Set it to 30 minutes:

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

5. Run getSite again and expect 1800, then trigger a new deploy.

The guide says 1800 seconds is the most you can set through the API. A larger value returns JSONHTTPError: Unprocessable Entity. Netlify support can set a longer limit: open a support request with your Site ID. Netlify’s guide on build length also says Business-level customers can run much longer builds, and mentions some with a 3 hour timeout.

Fix: build somewhere else and deploy the output

If no limit is enough, move the build off Netlify. The build length guide says manual deploys have no build time limit, because a manual deploy has no build step. Build in your own CI, then upload the output folder with the CLI:

npm ci
npm run build
netlify deploy --prod --dir=public

The time a manual deploy takes then depends mostly on how big your files are and how many there are.

Cause 3: a step hangs partway through

How to tell it’s yours: the log stops at a specific step, such as fetching data from a CMS or API, and stays silent for many minutes until the timeout. Nothing after that line ever prints.

Fix: make the stuck step finish or fail fast

1. Note the last line before the gap. That step either started a process that never returns or is waiting on something.
2. Run that step alone, locally, with the same environment variables the Netlify build uses. A missing or wrong variable that points a fetch at the wrong host can hang it.
3. Add timeouts to network calls in build scripts, so a slow upstream fails the build quickly with a clear error. That beats hanging silently until the limit.
4. If the step looks fine locally, use the ps auxw trick from Cause 1 to see what is still running on Netlify.

When the cache is the problem

A build that was fast yesterday and slow today, with no code change, can come from the cache. Netlify’s error reference recommends retrying a stalled deploy with Retry without cache with the latest branch commit. That rules out a corrupt cache. The troubleshooting tips also explain how the cache is keyed. A production deploy loads only the production branch cache. A Deploy Preview or branch deploy loads its own cache, and falls back to the production cache until its first successful build. So the first preview on a new branch can be slower than later ones.

If a retry without cache passes, the old cache was at fault. If it times out too, a cold install plus the build is over the limit, and you are back to Cause 2.

The deploy page also has a Why did it fail? button. The error reference says getting a diagnosis this way doesn’t use any credits. Selecting Fix with agent does use credits.

Keeping builds under the limit

• Make the build command exit cleanly. Run it locally in CI-like conditions and check that the prompt comes back. A command that hangs on your laptop will hang on Netlify.
• Never put watch or dev scripts in the build command. Keep build and dev as separate scripts, and point netlify.toml at the one-shot build.
• Watch the trend in build duration. Compare each build’s duration in the deploy log with your site’s limit. A build that creeps up release after release will cross it eventually, usually on a busy day.
• Skip builds you don’t need. The optimisation guide says [skip ci] or [skip netlify] in a commit message skips the build. An ignore command in netlify.toml can skip builds such as Dependabot pull requests:

  [build]
    ignore = "git log -1 --pretty=%B | grep dependabot"

  Fewer builds means fewer queued and wasted runs, though it won’t make a single build faster.
• Raise the limit on purpose. Set build_timelimit once you know the build is working, and write down why. That way the next person doesn’t raise it to hide a stuck process.

See Polylane as your AI SRE.