Fixing Vercel Builds That Run Out of Memory

A static site build on Vercel dies at the same point every few deploys: the log stops in the middle of image processing, and the final line says the build exceeded the memory limit, or simply that it was killed. Locally on a 32 GB laptop the same build passes every time. Vercel's build containers have a fixed amount of memory for each plan's machine size, and a static build that peaks above it is killed by the container, not by Node — so there is often no stack trace and no indication of what used the memory.

This guide fixes out-of-memory kills on a Next.js static export of a 6,500-page product catalogue on Vercel, where about one build in four failed. It shows how to measure peak memory, the two causes found — image processing concurrency and a large data file loaded whole — and the settings that keep the build well under the limit. It belongs to Netlify vs Vercel Deployment Strategies.

Symptoms

• Build log ends with Error: Command "npm run build" exited with SIGKILL during "Generating static pages", around page 4,000 of 6,500.
• On some runs, instead: FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory.
• The project had NODE_OPTIONS=--max-old-space-size=8192 set months earlier "to fix memory errors", on a build machine with 8 GB of memory.

That last point was the first problem: an 8 GB heap limit on an 8 GB machine means Node never stops itself; the container kills it first, with no useful message.

Step 1: Measure Peak Memory Locally Under the Same Limit

Reproduce the container's limit locally, with the same Node version, and record peak memory:

docker run --rm -m 8g -v "$PWD":/app -w /app node:20 bash -c \
  'npm ci && /usr/bin/time -v npm run build 2>&1 | tail -25' | grep -E 'Maximum resident|Elapsed|Exit status'

The build was killed at 8 GB in the container, as on Vercel. Without the limit, peak resident memory was 11.2 GB. Sampling memory every second with pidstat -r during the unconstrained run showed two spikes.

Cause 1: Unbounded Image Processing Concurrency

The site's prebuild script resized 7,800 product photos with sharp into three widths, using Promise.all over batches of 200. sharp's own thread pool used all CPUs, and each in-flight image held its decoded pixels in native memory — invisible to Node's heap limit. Supplier photos were often 5,000–6,000 pixels wide, about 90 MB decoded each. With dozens in flight, native memory reached 5.4 GB.

Bounding concurrency and telling sharp to limit its pixel cache fixed it:

import sharp from 'sharp';
import pLimit from 'p-limit';
sharp.concurrency(2);           // threads per image operation
sharp.cache({ memory: 50 });    // MB of libvips cache
const limit = pLimit(4);        // images in flight
await Promise.all(files.map((f) => limit(() => resize(f))));

Peak native memory for image processing fell to 0.9 GB, and the step took only 12% longer, because it had been memory-bound rather than CPU-bound. Caching the resized output between builds then removed most of the work anyway, as in Caching Processed Images Between Builds.

Cause 2: A Large Data File Loaded Whole

Every product page's generateStaticParams and page component imported catalogue.json — 640 MB, exported nightly from the product database. Next.js's static generation workers each loaded it, and the parsed objects took several times the file size in memory. The fix was to split the data at build start into one small JSON file per product plus a compact index:

// scripts/split-catalogue.mjs (runs before next build)
import { createReadStream } from 'node:fs';
import { parser } from 'stream-json';
import { streamArray } from 'stream-json/streamers/StreamArray';
const index = [];
for await (const { value: p } of createReadStream('data/catalogue.json').pipe(parser()).pipe(streamArray())) {
  await fs.writeFile(`data/products/${p.slug}.json`, JSON.stringify(p));
  index.push({ slug: p.slug, name: p.name, category: p.category });
}
await fs.writeFile('data/index.json', JSON.stringify(index));

generateStaticParams reads the 1.1 MB index; each page reads only its own product file. Streaming the parse keeps the split step itself under 200 MB. The same pattern applies to any generator; Fixing Eleventy Out-of-Memory Errors on Large Collections shows it in Eleventy.

Step 2: Set the Heap Limit With Headroom

With peak memory at 3.6 GB, the heap limit was set to leave room for native memory:

NODE_OPTIONS=--max-old-space-size=5120

5 GB of heap on an 8 GB machine leaves about 3 GB for sharp, esbuild, worker processes and the OS. If the heap grows past 5 GB in future, Node fails with a clear heap error and stack trace instead of an anonymous kill. A CI job records peak memory of every main-branch build and warns at 6 GB.

Step 3: Limit Static Generation Workers if Needed

Next.js generates static pages in parallel workers, each a separate process with its own memory. On an 8-core build machine, that is several copies of whatever each page imports. After the data split this was no longer a problem, but experimental.cpus in next.config.js can cap the worker count when page modules are inherently large. Other generators have equivalents: Astro builds pages in one process; Hugo uses goroutines in one process; Eleventy has no worker pool.

Measured Impact

The build got faster as well: less memory pressure meant fewer garbage collection pauses, and per-product files were quicker to read than re-parsing the whole catalogue.

Peak memory has stayed between 3.4 and 3.9 GB over the two months since, while the catalogue grew by 600 products.

Local reproduction in a memory-limited container was the step that made everything else possible; guessing on Vercel had cost two days.

Pitfalls & Rollback

• Heap limits at or above machine memory. Errors become silent kills.
• Unbounded Promise.all over images. Native memory is outside the heap limit.
• Importing huge data files in every page. Split them and load per page.
• Upgrading the machine first. It costs more and the next data growth hits the new limit.
• Rollback: each change is independent; reverting one shows its memory effect clearly in the recorded peak.

Conclusion

Static builds killed for memory on Vercel usually combine an oversized heap limit that hides the error, image processing with unbounded concurrency using native memory, and a large data file loaded whole into every page worker. Bounding sharp's concurrency, splitting the catalogue into per-product files and setting the heap limit with headroom took peak memory from over 11 GB to 3.6 GB, ended the failures and cut build time by a third — on the same machine size.

FAQ

How do I know a Vercel build ran out of memory?

The build log ends with a message that the build was killed or that it exceeded the memory limit, sometimes with SIGKILL or exit code 137 and no stack trace, or a JavaScript heap out of memory error from Node. The first means the container hit its memory limit; the second means Node's heap limit was reached before that.

Should I raise Node's max-old-space-size on Vercel?

Only up to a value safely below the container's memory, leaving room for native memory used by sharp, esbuild and the rest of the process. Raising it above the container limit turns a clear heap error into an opaque kill. Reduce peak memory first, then set the heap limit with headroom.

Why does image processing use so much memory?

Image libraries decode each image into raw pixels, which for a 6,000 by 4,000 photo is about 96 megabytes, and process several images in parallel, one per CPU by default. A few large originals processed at once can use gigabytes of native memory that the Node heap limit does not control.

Can I get a bigger build machine on Vercel?

Some plans offer larger build machines with more memory and CPUs, at a higher cost. They help when the build genuinely needs more memory. Most out-of-memory static builds instead have one or two causes, such as unbounded image concurrency or loading a large dataset at once, that are cheaper to fix.

Related

• Parent: Netlify vs Vercel Deployment Strategies — platform limits and settings.
• Fixing Netlify Builds That Exceed the Time Limit — the other common platform limit.
• Fixing Eleventy Out-of-Memory Errors on Large Collections — the same data pattern in Eleventy.
• Reducing Hugo Memory Usage on CI Runners — memory in Hugo builds.
• Handling Dynamic Routes in Next.js Static Export — generating many product routes.