Node.js Reference ยท CLI Flags
Node.js --max-old-space-size flag
Reference for node --max-old-space-size: raise or lower the V8 old-generation heap limit, check the effect, and understand out-of-memory crashes.
--max-old-space-size=<megabytes> sets the maximum size of V8's old generation, the part of the JavaScript heap where long-lived objects end up. When your program needs more than that, V8 first runs ever more aggressive garbage collections and finally aborts the process with a "JavaScript heap out of memory" error.
The default limit is chosen from the memory available to the process (and capped at a few gigabytes on 64-bit systems). Raising it lets memory-hungry jobs such as build tools or large data conversions finish. Lowering it makes a leaking program fail sooner and in a more predictable way, for example inside a small container.
// shell: node --max-old-space-size=4096 build.js
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Running out of heap is easy to cause and slow to clean up, so it is shown read-only. A loop such as the one below, started with a small limit, aborts the process:
// shell: node --max-old-space-size=24 hog.js const keep = []; while (true) keep.push({ id: keep.length }); // FATAL ERROR: ... JavaScript heap out of memory (the process ends with SIGABRT)
Syntax
// shell
node --max-old-space-size=<megabytes> <script>
NODE_OPTIONS=--max-old-space-size=<megabytes> node <script>
| Name | Description |
|---|---|
<megabytes> |
The old-generation limit in mebibytes. The value is a plain integer, such as 2048. |
Returns: nothing. Read the effective limit with v8.getHeapStatistics().heap_size_limit (bytes).
Edge cases: 0 is not "unlimited". The limit covers the JavaScript heap only; Buffer data, native addons and the executable itself live outside it, so the real process size can be larger. Worker threads have their own limits (see resourceLimits).
Usage notes
- Choose a limit below the memory you actually have. If the limit exceeds available RAM, the operating system may kill the process before V8 can report a clean error.
- Containers: recent Node.js versions read the container's memory limit when picking the default. If you set the flag, leave headroom (roughly 75% of the container limit) for buffers, the stack and native memory.
- A bigger heap is not a leak fix. If memory grows without bound, a larger limit only delays the crash; find the leak instead (Memory leaks). Garbage-collection pauses also get longer on very big heaps.
- Related flags:
--max-semi-space-sizetunes the young generation (often a cheap speed-up for allocation-heavy servers). List all V8 options withnode --v8-options. - Set it for child processes with
NODE_OPTIONS(inherited) or by passingexecArgvtofork(). - Heap out of memory is fatal. It cannot be caught with
try/catchoruncaughtException; the process aborts. On POSIX systems it ends with a signal such asSIGABRT. - Monitor before you crash: poll
process.memoryUsage()orv8.getHeapStatistics()and log or restart when usage approaches the limit.