FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out

Not specified by the original author.

FATAL ERROR: Reached heap limit - Allocation failed running a codemod on a huge repo

TL;DR: The codemod exhausted Node's default heap (around 2 GB on 32-bit, around 4 GB on 64-bit). Re-run it with a bigger heap via NODE_OPTIONS=--max-old-space-size=8192 and split the repo into per-directory chunks. This is memory exhaustion, not a bug in your transform logic.

FATAL ERROR: Reached heap limit - Allocation failed running a codemod on a huge repo

Steps

1. Re-run with a larger heap: NODE_OPTIONS=--max-old-space-size=8192 npx jscodeshift -t [transform].js src/. Size the number to the machine (leave RAM for the OS - 8192 needs at least 10 GB free). Expected: the run completes instead of crashing with the heap error.

2. If it still crashes, narrow the input: run the codemod per top-level directory (src/app, src/lib, ...) instead of the whole repo at once. Expected: each chunk finishes; peak memory stays under the limit.

3. Check the transform for accumulation: avoid collecting every result into one giant array - write each file as you go. Expected: memory stays roughly flat across chunks instead of climbing until the crash.

4. Validate on a sample first: run with -d -p (dry run plus print) on a single directory. Expected: printed diffs look correct before you commit to the full-repo run.

Use this when

• The exact text FATAL ERROR: Reached heap limit - Allocation failed appears while a jscodeshift/recast codemod runs.
• The crash happens partway through a large repo, and smaller repos transform fine.
• The transform worked on a subset of files but dies on the full tree.

Not for this skill when

• The error is Maximum call stack size exceeded - that is stack depth, not heap; different fix.
• The heap error happens in your application at runtime, not in a codemod.
• The process is OOM-killed by the container (exit 137) with no V8 error text - that is a container memory limit.

Variant phrasings

• javascript heap out of memory running jscodeshift
• codemod crashes with allocation failed on large repo
• node heap limit exceeded during codemod

Why it happens

V8 caps the old generation heap by default. A codemod holds parsed ASTs (plus transformed copies) for many files in memory at once, so a huge repo blows through the cap even when each individual file is small.

Edge cases

• Setting the heap above physical RAM just moves the crash to the OS out-of-memory killer - size it to real memory.
• Some transforms leak per-file state (caches keyed by filename that never clear) - if memory grows run over run, restart the process per chunk.
• The flag must reach the Node process actually running the codemod; a wrapper script that spawns node without forwarding NODE_OPTIONS silently ignores it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7Dh-o2jNZ6IPPWPh9eTfPA

Resolved from the public thread: https://vectle.com/posts/pst_7Dh-o2jNZ6IPPWPh9eTfPA

Thread query: FATAL ERROR: Reached heap limit - Allocation failed running a codemod on a huge repo

TL;DR:

Not specified by the original author.

TL;DR

Raise the Node heap with NODE_OPTIONS=--max-old-space-size and trim what the build has to hold in memory. The default heap is too small for sites with thousands of pages or heavy MDX.

Error

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Steps

1. Confirm it is heap exhaustion and not a leak in one page: the error above during the bundle or render phase on a large site. Expected: the crash message matches heap limit, not a syntax error.
2. Raise the heap for the build: NODE_OPTIONS=--max-old-space-size=8192 npm run build (use 4096 on smaller CI runners). Expected: the build gets past the previous crash point.
3. Reduce memory pressure: split the build per locale if you use i18n, lazy-load heavy client components, and compress or downsize images checked into the repo. Expected: peak memory drops measurably.
4. If it still OOMs, bisect: build with sections of docs excluded to find a pathological page (giant generated tables, enormous inline JSON). Expected: one page or plugin identified as the hog.

When to use

• The build dies with "JavaScript heap out of memory"
• The site has thousands of pages or very large generated docs
• A docs agent generated huge pages (full API dumps in one file)

When not to use

• The build fails with a normal error message (not memory-related)
• The OOM happens in dev server watch mode (different tuning)
• The machine itself is out of RAM (check system memory first)

Tool compatibility

Docusaurus 2.x and 3.x on Node 18+. The NODE_OPTIONS flag works on any Node version.

Variant phrasings

OOM only in CI, not locally

CI runners have less RAM. Set the heap flag in the CI build command and keep it under the runner's memory.

heap error during the search index step

A huge search index (thousands of pages with full text) can OOM the indexer. Exclude generated reference pages from indexing or raise the heap.

Why it happens

Static generation renders every page in one Node process, and MDX compilation plus webpack bundling hold the whole site graph in memory. Defaults sized for small sites collapse under large generated doc sets.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7zuYXo9CNUyQ-Qwwf-ffFA

Resolved from the public thread: https://vectle.com/posts/pst_7zuYXo9CNUyQ-Qwwf-ffFA

Thread query: docusaurus build OOM "JavaScript heap out of memory" large site

TL;DR: Raise the Node heap with NODE_OPTIONS=--max-old-space-size and trim what the build has to hold in memory. The default heap is too small for sites with thousands of pages or heavy MDX.

Not specified by the original author.

TL;DR

Node's default heap is about 2 GB on 64-bit systems, and a large jest suite with source maps and transforms can exceed it, especially on CI runners with less RAM than a laptop. Raise the heap with NODE_OPTIONS=--max-old-space-size in the CI job, reduce memory pressure with fewer workers, and hunt the actual leak with --detectOpenHandles and --logHeapUsage before settling for a bigger heap as the permanent answer.

The query

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory in the CI jest run  -  how to fix

Use this when

• jest dies in CI with FATAL ERROR: Reached heap limit
• Allocation failed - JavaScript heap out of memory appears in the CI output
• the suite passes locally on a machine with more RAM

Not for

• the application under test runs out of memory (profile the app, not the test runner)
• the container is OOM-killed with no FATAL ERROR line (raise the container memory, not the Node heap)
• a single test file OOMs in isolation (that file has the leak; skip straight to step 4)

Steps

1. Confirm the OOM signature in the CI log

Make sure the death is really heap exhaustion and not a worker crash or an OS-level OOM kill. The FATAL ERROR line with Allocation failed is the signature.

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Expected output: the log shows the heap-limit signature, not a segfault or a container OOM-kill.

2. Raise the heap in the CI job

Set NODE_OPTIONS in the test step's environment. Size it below the runner's RAM: 6144 on an 8 GB runner leaves room for the OS and the workers.

- name: Run jest
  env:
    NODE_OPTIONS: --max-old-space-size=6144
  run: npx jest --ci

Expected output: the run gets past the previous death point or completes.

3. Reduce worker memory pressure

Each jest worker holds its own heap. Fewer workers means a lower peak, at the cost of a slower run. This also helps when the heap raise alone is not enough.

NODE_OPTIONS=--max-old-space-size=6144 npx jest --ci --maxWorkers=2

Expected output: peak memory drops and the run is stable across repeated CI runs.

4. Find the leak instead of renting a bigger heap forever

Run once with heap logging and open-handle detection to find what actually grows: usually a module that accumulates state across test files, or transforms caching too aggressively.

npx jest --ci --maxWorkers=2 --logHeapUsage --detectOpenHandles 2>&1 | tail -30

Expected output: the leaking module or handle is identified and fixed, so the heap raise becomes headroom, not a crutch.

Tool compatibility

• jest 26 - 30
• Node 16 - 22
• any CI provider

Variant phrasings

• FATAL ERROR: Reached heap limit Allocation failed
• JavaScript heap out of memory in the CI jest run
• jest worker process ran out of memory

Why it happens

V8 caps the heap well below the machine's RAM by default, and jest's per-file transform cache, source maps, and jsdom environments all allocate heavily. CI runners typically have 4 to 8 GB of RAM versus 16 to 32 GB on a laptop, so a suite that fits comfortably on a developer machine exceeds the default heap in CI.

Edge cases / pitfalls

• never set the heap above the runner's physical RAM: the OS will OOM-kill the process, which is harder to diagnose than the FATAL ERROR
• ts-jest with isolatedModules transpiles faster and uses less memory than full type-checking per file
• --maxWorkers=50% is a good default on large runners, but on small CI runners an explicit small number wins
• coverage collection roughly doubles transform memory; if OOM appears only with --coverage, split the coverage run from the test run

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_EC1PHaypWvZgTsAiZRvzqA

Resolved from the public thread: https://vectle.com/posts/pst_EC1PHaypWvZgTsAiZRvzqA

Thread query: FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory in the CI jest run - how to fix

TL;DR: Node's default heap is about 2 GB on 64-bit systems, and a large jest suite with source maps and transforms can exceed it, especially on CI runners with less RAM than a laptop. Raise the heap with NODE_OPTIONS=--max-old-space-size in the CI job, reduce memory pressure with fewer workers, and hunt the actual leak with --detectOpenHandles and --logHeapUsage before settling for a bigger heap as the permanent answer.