Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท child_process, worker_threads and cluster

Node.js worker resourceLimits option

Reference for the Worker resourceLimits option in Node.js: maxOldGenerationSizeMb, maxYoungGenerationSizeMb, codeRangeSizeMb, stackSizeMb and out-of-memory errors.

The resourceLimits option of new Worker() sets memory limits for the JavaScript engine instance that runs inside one worker thread. It lets you contain a task that might use too much memory: when the worker reaches its limit, only that worker is terminated, and the main thread keeps running.

Without limits, a worker uses the engine's defaults, which are generous and mostly based on the machine's memory. Limits are most useful in worker pools that run untrusted or unpredictable jobs, such as image processing or user-supplied data.

NODE
import { Worker } from "node:worker_threads";

const worker = new Worker("./task.js", {
  resourceLimits: { maxOldGenerationSizeMb: 64, maxYoungGenerationSizeMb: 8 },
});

Try it

Node.js A worker that runs out of memory

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 Reading the limits from inside a worker

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.

Syntax

NODE
new Worker(filename, { resourceLimits: {
  maxOldGenerationSizeMb?: number,
  maxYoungGenerationSizeMb?: number,
  codeRangeSizeMb?: number,
  stackSizeMb?: number,
} })
worker.resourceLimits: ResourceLimits
worker_threads.resourceLimits: ResourceLimits   // inside the worker
Name Description
maxOldGenerationSizeMb Maximum size of the main (old) heap in megabytes, where long-lived objects live.
maxYoungGenerationSizeMb Maximum size of the young heap, where new objects are allocated.
codeRangeSizeMb Size of a pre-allocated memory range for generated code.
stackSizeMb Default maximum stack size of the thread (default 4).

Returns / reads: worker.resourceLimits is an object with all four fields; it holds the values in effect for that worker (including defaults for fields you did not set) and is an empty object after the worker has exited. Inside a worker, the resourceLimits export holds the same values.

Errors / edge cases: when a heap limit is hit, the worker emits an 'error' event with err.code === "ERR_WORKER_OUT_OF_MEMORY" and then 'exit' with code 1. Very small stack limits can crash the whole process, not just the worker.

Usage notes

  • Limits apply to the JavaScript heap only. Buffers, ArrayBuffers and SharedArrayBuffers live outside it and are not counted, so a worker can still use a lot of memory through them.
  • Always listen for 'error'. An unhandled 'error' event on a worker throws in the main thread. Pair it with 'exit' to clean up pool bookkeeping.
  • Set both generations in a sensible ratio. Too small a young generation makes the garbage collector run constantly; too small an old generation kills workers early on legitimate jobs.
  • Raising the limit is allowed, too. You can give a worker more heap than the default when a job needs it, instead of raising limits for the whole process with --max-old-space-size.
  • Do not set the stack size close to zero. Deep recursion under a tiny stackSizeMb can abort the process. Keep the default unless you have measured.
  • Unset fields get defaults. Read worker.resourceLimits to see the values actually in effect, including the ones you did not set.
  • Other protection: the terminate() method and a timeout in your pool code guard against runaway CPU use, which memory limits do not.