node · npm
The message
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
What it means
The V8 heap hit its ceiling and node gave up on its own — the operating system did not kill it, node decided it could not grow further and stopped. The cause is a big type-check or bundle, a build with source maps on a large project, or leaking code such as accumulating everything in an array. export NODE_OPTIONS=--max-old-space-size=4096 raises the ceiling to 4 GB and is often enough, but the machine has to actually have that much RAM, and if a container's limit is lower the operating system kills the process instead, which shows up as exit code 137. If the number keeps having to grow, the cause is a leak and not the limit.
The fix
export NODE_OPTIONS=--max-old-space-size=4096- Printed by
- node
- npm
- 20
With npm the cause sits in the first code XXXX line rather than the last six npm ERR! lines, and when the failure comes from the dependency tree or a native build instead of your own code, deleting node_modules and installing again clears about half of them.
Reading an error message
- Read from the first line down. The lower you go the more it is about the tool’s internals; the cause is usually at the top.
- If there is a file and a line number, start there — not the top stack frame, but the topmost line that names a file you wrote.
- Search the message verbatim, but strip your own paths and variable names first; those are what stop the search from matching.
- The same condition is worded differently across tool versions. If results look wrong, add the version number to the query.
- Before pasting a fix, check what it throws away. Some of these cannot be undone.
Common questions
Q. What does “FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory” mean?
The V8 heap hit its ceiling and node gave up on its own — the operating system did not kill it, node decided it could not grow further and stopped. The cause is a big type-check or bundle, a build with source maps on a large project, or leaking code such as accumulating everything in an array. export NODE_OPTIONS=--max-old-space-size=4096 raises the ceiling to 4 GB and is often enough, but the machine has to actually have that much RAM, and if a container's limit is lower the operating system kills the process instead, which shows up as exit code 137. If the number keeps having to grow, the cause is a leak and not the limit.
Q. How do I fix it?
export NODE_OPTIONS=--max-old-space-size=4096 — before running it, check the explanation above for what this command discards.
Q. Which tool prints this?
node. It sits under npm, and the message runs to 13 words.