skip to content

In Node.js 24, how do you cap a worker_threads.Worker's heap with resourceLimits, what happens when the worker exceeds it, and what does the cap not cover?

level: seniorimportance: should knowfreq 35%

answer

  1. a heap per isolate
  2. constructor option, four fields
  3. the thread dies, the process lives
  4. ArrayBuffers sit outside it

basics

~20 s

Pass resourceLimits such as maxOldGenerationSizeMb to new Worker(). Exceeding it terminates only that worker, which emits 'error' with ERR_WORKER_OUT_OF_MEMORY and then 'exit'. The cap covers the JS heap only, not ArrayBuffers or other external memory.

solid answer

~40 s

Every worker has its own V8 heap, so `new Worker(file, { resourceLimits: { maxOldGenerationSizeMb: 256 } })` caps that worker's main heap; `maxYoungGenerationSizeMb`, `codeRangeSizeMb` and `stackSizeMb` (default 4) cover the rest. When the worker hits the limit, Node terminates that thread, the `Worker` emits `'error'` with `ERR_WORKER_OUT_OF_MEMORY`, then `'exit'`, and the main thread keeps running. The limits cover only the JS engine: `ArrayBuffer`s, `Buffer`s and other external memory are excluded, and the process can still abort on a global out-of-memory condition. A command-line `--max-old-space-size` overrides `maxOldGenerationSizeMb`, and V8 flags cannot be passed through `execArgv`. Since Node 24.0.0 the parent can watch a worker's heap with `worker.getHeapStatistics()`.

code

javascript · 13 lines
javascript
import { Worker } from 'node:worker_threads';

const code = `
  const keep = [];
  for (;;) keep.push(new Array(1e5).fill(Math.random()));
`;

const worker = new Worker(code, {
  eval: true,
  resourceLimits: { maxOldGenerationSizeMb: 64 },
});
worker.on('error', (err) => console.log('error event:', err.code));
worker.on('exit', (exitCode) => console.log('exit event, code', exitCode));

go deeper

for a junior

Recall that each worker has its own heap and that resourceLimits on the Worker constructor can cap it.

for a middle

Explain the four resourceLimits fields, the ERR_WORKER_OUT_OF_MEMORY error followed by 'exit', and the override by a command-line --max-old-space-size.

for a senior

Budget memory for the whole process: per-worker heap caps plus external buffers times the pool size, and watch worker heaps with getHeapStatistics().

for a principal

Decide where memory isolation for heavy jobs should live, inside a process via worker caps or at the process and container level, and what each failure costs users.

## Why each worker has its own heap Every `worker_threads.Worker` runs in its own **V8 isolate**, and each isolate has its own garbage-collected heap. A report generator that builds a large in-memory model in a worker therefore grows that worker's heap, not the main thread's. That isolation is what makes a per-worker cap possible: one runaway job can be stopped without touching the thread that serves requests. ## The resourceLimits option The cap is set when the worker is created, through the `resourceLimits` option of `new Worker(filename, options)`. It has four fields: | Field | What it limits | Documented default | |---|---|---| | `maxOldGenerationSizeMb` | The main heap, where long-lived objects live | None given | | `maxYoungGenerationSizeMb` | The heap space for recently created objects | None given | | `codeRangeSizeMb` | A pre-allocated range for generated code | None given | | `stackSizeMb` | The thread's maximum stack size | `4` | The documentation warns that small `stackSizeMb` values "may lead to unusable Worker instances". The configured values are readable from the parent as `worker.resourceLimits` (an empty object once the worker has stopped) and from inside the worker as `require('node:worker_threads').resourceLimits`. Those properties echo what was passed to the constructor; the heap limit V8 actually applies is the `heap_size_limit` reported by `v8.getHeapStatistics()` inside the worker. Two interactions with command-line flags matter: - A command-line `--max-old-space-size` **overrides** `maxOldGenerationSizeMb`, and `--max-semi-space-size` overrides `maxYoungGenerationSizeMb`. A cap that seems to be ignored is often this. - The `execArgv` option cannot carry V8 options such as `--max-old-space-size`; the docs say they are not supported, and passing one is rejected with `ERR_WORKER_INVALID_EXEC_ARGV`. `resourceLimits` is the per-worker way to set a heap size. ## What happens when a worker hits the limit "Reaching these limits leads to termination of the `Worker` instance." Concretely: 1. The worker thread stops executing JavaScript. 2. The parent's `Worker` emits `'error'` with an error whose `code` is `ERR_WORKER_OUT_OF_MEMORY` ("The `Worker` instance terminated because it reached its memory limit"). 3. `'exit'` follows as the final event. The main thread survives, provided it listens for `'error'`; an `EventEmitter` with no `'error'` listener rethrows the error, which would take down the process instead. A pool should treat this like any other worker failure: fail the task, record it, and start a fresh worker. ## What the cap does not cover This is where most surprises come from. The documentation states that the limits "only affect the JS engine, and no external data, including no `ArrayBuffer`s". So: - **Binary data escapes the cap.** Image pixels, decoded file contents and anything held in `Buffer`s or typed arrays live in `ArrayBuffer` backing stores outside the V8 heap. A worker can stay under `maxOldGenerationSizeMb` while holding a gigabyte of buffers. - **`SharedArrayBuffer` memory** is not counted against any one worker. - **Native allocations** by add-ons and Node internals are outside it. - **The process can still die.** "Even if these limits are set, the process may still abort if it encounters a global out-of-memory situation." A container memory limit counts the process's whole resident memory: every isolate's heap, all external memory and the main thread together. So budget memory at the process level: roughly the main thread's heap plus, per worker, its heap cap and the external buffers it may hold, multiplied by the pool size, with headroom below the container limit. ## Choosing a cap A cap is useful only if it sits between normal and pathological use: - Measure the peak heap a typical job reaches, for example by sampling `worker.getHeapStatistics()` on representative inputs. - Set `maxOldGenerationSizeMb` comfortably above that peak, so ordinary jobs never hit it and a runaway input fails fast instead of starving the process. - Count the failures: a steady stream of `ERR_WORKER_OUT_OF_MEMORY` means either the cap is too low or some inputs need to be rejected before they reach a worker. ## Observing a worker's heap Node 24 adds tools the parent can use without code inside the worker: - `worker.getHeapStatistics()` (added in v24.0.0) returns a promise for the same object as `v8.getHeapStatistics()`, measured inside that worker, or rejects with `ERR_WORKER_NOT_RUNNING` once it has stopped. - `worker.getHeapSnapshot()` returns a promise for a readable stream containing a V8 heap snapshot of the worker, for leak analysis. - `worker.performance.eventLoopUtilization()` shows how busy the worker's loop is. Sampling `getHeapStatistics()` before and after jobs, or on a timer, shows whether a worker's heap ratchets up across tasks, which is the signature of state leaking between jobs in a long-lived pooled worker. ## Summary for an interview - Set `resourceLimits` per worker; it caps the JS heap and stack, nothing else. - Exceeding it ends that worker with `ERR_WORKER_OUT_OF_MEMORY` via `'error'`, then `'exit'`. - Buffers and other external memory are outside the cap, so budget the whole process against the container limit.

  • A worker with maxOldGenerationSizeMb: 256 still drives the container to its memory limit. What is the likely cause?
    The cap covers only the V8 heap. If the worker holds decoded images or file contents in `Buffer`s or typed arrays, that memory lives in `ArrayBuffer` backing stores outside the heap and is not limited. Multiply that by the pool size and add the main thread, and the process's resident memory can exceed the container limit while every heap stays under its cap.
  • Why might a worker ignore the maxOldGenerationSizeMb you set?
    Because a `--max-old-space-size` given on the command line, for example through `NODE_OPTIONS`, overrides `maxOldGenerationSizeMb` for workers. `worker.resourceLimits` still echoes the value you passed, so check `heap_size_limit` from `worker.getHeapStatistics()` (Node 24) to see the limit V8 actually applies.

  • Believing resourceLimits caps Buffers and ArrayBuffers held by the worker
  • Expecting a worker hitting its heap limit to crash the whole process
  • Passing --max-old-space-size through execArgv to size one worker
  • Assuming per-worker caps guarantee the process stays under the container limit
  • Assuming all workers share the main thread's single heap

Assumes Node 24; worker.getHeapStatistics() was added in v24.0.0, while resourceLimits itself dates from v13.2.0 and v12.16.0.