A Node 24 service in a 1 GiB container is killed by the orchestrator instead of failing with 'JavaScript heap out of memory'; how should you set its V8 heap limit?
answer
- two ceilings, which one is lower
- read heap_size_limit inside the container
- old space only, in MiB
- headroom for memory off the heap
- a percentage of the cgroup limit
basics
~20 sSet V8's heap limit explicitly and well below the container limit, leaving room for memory outside the heap: --max-old-space-size in MiB, or in Node 24.6 and later --max-old-space-size-percentage, which uses the cgroup limit when one is set. A leak then fails inside V8, with diagnostics.
solid answer
~50 sThere are two ceilings. V8 enforces a heap limit, `heap_size_limit` in `v8.getHeapStatistics()`, chosen from system resources unless you pass `--max-old-space-size`; the container enforces a limit on the whole process's memory. If the process reaches the container's limit first, the kernel kills it with no output from Node. So check what V8 picked inside the container, then set the limit explicitly: `--max-old-space-size` takes MiB and bounds only the old space, so leave headroom for the young generation, Buffers and other memory outside the heap, native code and thread stacks, and the extra memory a heap snapshot needs. For a 1 GiB container that is typically 60 to 75 percent. Node 24.6 added `--max-old-space-size-percentage`, computed from the cgroup limit when one is set. A leak then ends in V8's `JavaScript heap out of memory` error, with the last GC lines and a stack, and `--heapsnapshot-near-heap-limit` can write evidence first.
code
bash · 9 lines# Inside the container: what did V8 pick, and what is the cgroup limit?
node -p "v8.getHeapStatistics().heap_size_limit / 1024 / 1024"
node -p "process.constrainedMemory() / 1024 / 1024"
# Fixed size, in MiB
node --max-old-space-size=700 server.js
# Node 24.6 or later: 70 percent of the cgroup limit
NODE_OPTIONS="--max-old-space-size-percentage=70" node server.jsgo deeper
Recall that --max-old-space-size takes MiB, bounds V8's old space, and that v8.getHeapStatistics().heap_size_limit shows the limit actually in force.
Explain why the process uses more memory than its heap limit: young generation, Buffers and other off-heap memory, code and thread stacks.
Size the limit from measured rss and heap at peak, leave room for a heap snapshot, and explain why a V8 OOM with a stack beats a silent container kill.
Choose a fleet default: an explicit MiB value per service, or a percentage of the cgroup limit that follows each deployment's container size, and how Buffer-heavy services opt out.
## Two ceilings, and which one fires A Node.js process in a container lives under **two independent memory limits**: - **V8's heap limit.** V8 refuses to grow its JavaScript heap past `heap_size_limit` (reported by `v8.getHeapStatistics()`). Near that limit it spends more and more time collecting garbage; if it still cannot allocate, it prints the last few GC lines and a JavaScript stack and stops with a fatal error such as `FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory`. - **The container's memory limit.** The kernel enforces a limit on the whole process, roughly its resident memory. Crossing it ends the process from outside, with **no message from Node**, no stack and no chance to write a snapshot. How the kill is reported belongs to the container material; what matters here is that Node never sees it coming. The symptom in the question, a kill without the V8 error, means the container limit was reached first: either V8's limit sits at or above it, or memory outside the heap pushed the process over. ## What V8 picks by default Without a flag, the heap limit is a V8 default **determined by system resources**. Do not assume it matches the container; read it inside the container: ```bash node -p "v8.getHeapStatistics().heap_size_limit / 1024 / 1024" node -p "process.constrainedMemory() / 1024 / 1024" ``` `process.constrainedMemory()` returns the limit the OS imposes, from cgroups on Linux, or `0` when there is none or it is unknown. If the first number is close to or above the second, the container's limit is likely to be hit first. ## Sizing the limit `--max-old-space-size=SIZE` is given in **MiB** and sets the maximum size of V8's **old space**, where long-lived objects end up. It is not a cap on the process. The process's memory is roughly: | Part | Bounded by `--max-old-space-size`? | |---|---| | Old space (long-lived objects) | Yes | | Young generation (three times `--max-semi-space-size`) | No | | Buffer and ArrayBuffer storage (`external`) | No | | Compiled code, native allocations, addons | No | | Thread stacks for the main thread, threadpool and workers | No | | Extra memory while a heap snapshot is built (the docs say about twice the heap in total) | No | So the budget is the container limit minus everything in the "No" rows, measured under real load: 1. Run the service at peak and record `rss`, `heapUsed` and `external` from `process.memoryUsage()`. 2. The gap between `rss` and the heap is your off-heap baseline; Buffer-heavy services (proxies, file processing) have a large one. 3. Set the old-space limit so that its ceiling plus that baseline plus a margin stays under the container limit. The Node docs' own example leaves a quarter free: 1536 MiB on a 2 GiB machine. For 1 GiB, values between about 600 and 768 MiB are typical; a Buffer-heavy service needs less. Setting `--max-old-space-size=1024` in a 1 GiB container is the classic mistake: the heap may legally reach the whole budget, and everything else pushes the process over first. ## The percentage form in Node 24 Node 24.6.0 added **`--max-old-space-size-percentage=percentage`**. It accepts a value greater than 0 and up to 100, takes precedence over `--max-old-space-size` when both are given, and computes the size from the process's **constrained memory** (the cgroup limit, through libuv) when one is set, falling back to total physical memory otherwise. One setting such as `70` then follows each deployment's container size: ```bash NODE_OPTIONS="--max-old-space-size-percentage=70" node server.js ``` Both flags are allowed in `NODE_OPTIONS`, which lets the platform set them without editing the start command. ## Why failing inside V8 is better The process dies either way, but the V8 failure is far more useful: - The output includes the **last few GCs** and a **JavaScript stack**, so you can see the heap was full and where allocation failed. - `--heapsnapshot-near-heap-limit=max_count` writes up to that many heap snapshots as the heap approaches the limit, evidence a kernel kill never leaves. It needs memory itself, so it works reliably only when the heap limit leaves room below the container limit. - The approach to the limit is visible: GC time rises and latency degrades before the crash. Raising the limit is not a fix for a leak; it only moves the crash later. The limit's job is to make sure the leak fails where Node can tell you what was retained.
- The process dies either way; why is a V8 heap out-of-memory failure better than a kernel kill?V8's failure prints the last few garbage collections and a JavaScript stack, and with `--heapsnapshot-near-heap-limit` Node can write heap snapshots as the heap nears the limit. A kill from the container's memory limit gives Node no chance to print or write anything, so you learn only that memory ran out, not what was holding it.
- What happens if --max-old-space-size and --max-old-space-size-percentage are both set, for example one in NODE_OPTIONS?The percentage flag takes precedence. Node computes it from the constrained memory libuv reports, the cgroup limit, when one is set, and from total physical memory otherwise. A value of 0 or less, or above 100, is rejected with an error at startup.
- Set --max-old-space-size to the container limit, 1024 for 1 GiB.
- --max-old-space-size caps the total memory of the Node process.
- Buffer contents count against --max-old-space-size.
- --max-old-space-size takes its value in bytes.
- Raising the heap limit is how you fix a memory leak.
- V8's default heap limit always matches the container limit.
Assumes Node 24.6 or later: --max-old-space-size-percentage was added in 24.6.0; --max-old-space-size works the same in every supported release.