Skip to content
Tutorials Center
My learning

Topics

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.

NODE
// shell: node --max-old-space-size=4096 build.js

Try it

Node.js The flag changes the reported limit

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.

Node.js Using NODE_OPTIONS and watching heap usage

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:

NODE
// 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

NODE
// 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-size tunes the young generation (often a cheap speed-up for allocation-heavy servers). List all V8 options with node --v8-options.
  • Set it for child processes with NODE_OPTIONS (inherited) or by passing execArgv to fork().
  • Heap out of memory is fatal. It cannot be caught with try/catch or uncaughtException; the process aborts. On POSIX systems it ends with a signal such as SIGABRT.
  • Monitor before you crash: poll process.memoryUsage() or v8.getHeapStatistics() and log or restart when usage approaches the limit.