Node.js JavaScript heap out of memory

What this failure means

The Node.js process ran out of heap memory during the build. This is common in large Webpack, Next.js, or Jest builds where the default V8 heap limit is too low for the amount of modules being processed.

Symptoms

Faultline looks for one or more of these log fragments:

FATAL ERROR: Reached heap limit Allocation failed
JavaScript heap out of memory
FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed
Ineffective mark-compacts near heap limit
<--- Last few GCs --->
<--- JS stacktrace --->
Allocation failed - JavaScript heap out of memory
ERR_WORKER_OUT_OF_MEMORY

Diagnosis

The Node.js process ran out of heap memory during the build. This is common in large Webpack, Next.js, or Jest builds where the default V8 heap limit is too low for the amount of modules being processed.

Fix steps

1. Increase the Node.js heap limit: set NODE_OPTIONS=--max-old-space-size=4096 (or higher) before the build command.
2. For npm scripts, add it inline in package.json scripts: "build": "NODE_OPTIONS=--max-old-space-size=4096 next build".
3. For Jest OOM: pass --maxWorkers=2 or --runInBand to serialize test execution and lower peak memory.
4. Upgrade the CI runner to a higher-memory tier — heap expansion is not free; more RAM is the most reliable fix.
5. Identify the heap consumer: add --inspect or run node --max-old-space-size=2048 --trace-gc and profile with Chrome DevTools.
6. Break the build into smaller increments (e.g., build packages individually in a monorepo).

Validation

• Re-run the local reproduction command after the fix.
• NODE_OPTIONS=—max-old-space-size=4096 npm run build

Why it matters

Node.js’s V8 engine has a default heap size limit (typically 512 MB–1.5 GB depending on the platform). Large bundlers and test suites that load many modules simultaneously can exceed this limit. This is especially frequent when running production builds or full test suites in a memory-constrained CI environment.

Prevention

• Set NODE_OPTIONS=--max-old-space-size=4096 globally in the CI environment configuration (e.g., as a CI environment variable).
• Monitor bundle size with webpack-bundle-analyzer, next build output, or source-map-explorer to catch regressions early.
• Split large monorepo packages so no single process must compile the whole dependency graph at once.
• Add a CI step that fails if the peak RSS of the build process exceeds a defined threshold.

Try it locally

NODE_OPTIONS=--max-old-space-size=4096 npm run build

How Faultline detects it

Use faultline explain node-out-of-memory to see the full playbook.

faultline analyze build.log
faultline explain node-out-of-memory

Generated from playbooks/bundled/log/build/node-out-of-memory.yaml. Do not edit directly.