Memory in Node.js

Memory in a Node process

A Node server runs JavaScript, but it also runs V8, Node native code, network libraries, file work, and sometimes binary data. Looking only at JavaScript objects can therefore tell an incomplete story. A healthy memory investigation starts by naming which kind of memory is growing.

This lesson continues from Memory in large apps. That lesson asks whether an app keeps data too long. Here, the server question is also practical: can this process stay below its machine or container memory limit while handling real requests?

We will read counters, choose a heap limit, make a snapshot, and recognize an out-of-memory report. These tools do not replace ordinary ownership decisions. They make the next investigation small enough to do calmly.

Bytes before memory counters

A byte is a small unit of storage. Counters such as external are reported in bytes, so it helps to see one familiar amount before reading a server report.

1const bytes = new ArrayBuffer(1024 * 1024);2console.log(bytes.byteLength);

Line 1 creates an ArrayBuffer with 1024 times 1024 bytes. Line 2 prints its length. The real output is 1048576, which is one mebibyte expressed as bytes. The example runs in a browser, so it connects the number to code you can edit here.

Server tools often show a large number such as 10485760. Do not guess from the digits. Divide by 1024 twice when you need a rough megabyte value, and compare the same counter over time rather than treating one sample as a verdict.

Heap limits and containers

V8's heap limit is the maximum managed JavaScript heap V8 is willing to grow toward. Node exposes the current limit through v8.getHeapStatistics().heap_size_limit. The value changes when you start Node with a different old-space limit.

1const v8 = require("node:v8");2console.log(v8.getHeapStatistics().heap_size_limit);

Line 1 loads Node's built-in V8 module. Line 2 prints the current heap limit in bytes. This is Node-only code, so the lesson does not offer it to the browser editor. The lesson test starts child processes with 32 MB and 64 MB flags and proves only that the 64 MB process reports a larger limit.

node --max-old-space-size=64 app.js

The flag is measured in megabytes and constrains V8 old space. It is useful for making a service fail nearer to an intentional boundary, but it is not a whole-process fence. RSS can still include native code, stacks, code pages, and Buffer payload bytes.

1const limitMB = 64;Run2const containerMB = 128;3const headroomMB = containerMB - limitMB;4console.log(headroomMB);

In a container, set the heap flag below the container's memory limit. The difference is headroom for everything that is not ordinary V8 heap data. Without it, the operating system may kill the whole process before V8 can give you a useful heap failure.

Reading process.memoryUsage()

Memory usage counters are a snapshot of categories Node can report for its current process. Call process.memoryUsage() when you want those categories. Read them together; no one field tells the whole memory story.

1const usage = process.memoryUsage();2console.log(Object.keys(usage).join(","));

Line 1 asks Node for a fresh usage object. Line 2 prints its property names. The real child-process output is rss,heapTotal,heapUsed,external,arrayBuffers. The order matters here because it makes the five counters easy to find in a log.

rss is all memory currently held by the Node process in RAM. heapTotal is V8 heap capacity currently reserved for JavaScript objects. heapUsed is JavaScript heap space currently in use. external is native memory V8 accounts alongside the heap. arrayBuffers is the part associated with ArrayBuffers and Node Buffers.

Sample at meaningful boundaries: before a batch, after a batch, and after work should be released. Logging every request can create noise and can itself retain strings. For a long-running service, add a small metrics series with the same five counters.

Buffers and external memory

A Buffer is Node's convenient binary-data type. It is useful for files, network payloads, images, and cryptographic data. Its payload is not an ordinary JavaScript object graph, so a large Buffer can raise external memory far more than heapUsed.

1const before = process.memoryUsage();2const data = Buffer.alloc(10 * 1024 * 1024);3const after = process.memoryUsage();4console.log("buffer bytes", data.length);5console.log("external grew", after.external > before.external);6console.log("arrayBuffers grew", after.arrayBuffers > before.arrayBuffers);

Line 1 saves counters before allocation. Line 2 makes a ten-megabyte Buffer. Line 3 gets a second snapshot. Lines 4 through 6 print facts about the allocation. The child-process test confirms that external grows by at least 10 MB while heapUsed grows much less; it never assumes an exact platform-specific counter value.

1const before = { heapUsedMB: 3, externalMB: 1 };Run2const bufferMB = 10;3const after = { heapUsedMB: 3, externalMB: 11 };4console.log(after.externalMB - before.externalMB);

1const bytes = sizeMB * 1024 * 1024;2const data = Buffer.alloc(bytes);3console.log(data.length);

A Buffer is not free simply because it is outside the V8 heap. Keep binary work bounded: limit concurrent uploads, avoid collecting every file in an array, and let each completed request drop its references. Watch RSS with external memory when binary workloads grow.

Heap snapshots in Node.js

A heap snapshot is a file describing objects V8 sees in its JavaScript heap at one moment. It is most useful when you compare before-and-after snapshots or inspect what retains a collection that should have disappeared.

1const v8 = require("node:v8");2const filename = v8.writeHeapSnapshot();3console.log(filename);

Line 1 loads Node's V8 helpers. Line 2 writes a snapshot file and prints its filename. Run this deliberately in a safe environment because making a snapshot needs memory and can pause work. Open the resulting file in Chrome DevTools' Memory panel.

node --heapsnapshot-signal=SIGUSR2 app.js
kill -USR2 <pid>

The first line starts Node with a signal handler for snapshots. The second line sends SIGUSR2 to the process. This is handy when code cannot easily reach the problem moment itself, but use a process supervisor and deployment rules appropriate for your service.

node --max-old-space-size=64 --heapsnapshot-near-heap-limit=1 app.js

This command asks Node to write one snapshot when V8 nears its configured heap limit. It is an emergency clue, not a cure. For reading the result, continue with Heap snapshots in depth and look for retaining paths.

Diagnosing out-of-memory crashes

An out-of-memory crash happens when V8 cannot grow the JavaScript heap enough for the next allocation. A typical report contains FATAL ERROR: ... JavaScript heap out of memory. Read that phrase first; it identifies a V8 heap problem, not every possible reason a container stopped.

1const orders = [];2while (true) {3  orders.push("tea ".repeat(10000));4}

Line 1 keeps an array reachable. Line 3 keeps adding long strings forever. Run this only in an isolated child process with a tiny limit. The lesson test uses --max-old-space-size=32, verifies a non-zero exit code, and checks stderr for heap out of memory.

Use a short checklist: confirm whether the report says JavaScript heap out of memory, inspect heap and external counters, reproduce with a safe limit, capture a snapshot if possible, and find the collection or retaining path that grows. Raising a limit can buy time, but it hides an unbounded array or cache only temporarily.

A small server memory routine

Start with a budget. Know the container memory limit, choose a smaller V8 old-space limit, and leave room for native work. Then choose a workload boundary, such as an upload batch or a report request, where you can compare counters before and after.

Keep collections bounded. A cache needs a maximum size or expiration. A file pipeline should stream when it can process pieces in order. A JSON endpoint needs a request size limit before one request turns into a huge string and parsed object graph at the same time.

Alert on a trend and tie it to a workload. A rising heap after each completed job suggests retained JavaScript objects. Rising external memory during image work suggests binary concurrency. Rising RSS with neither clue deserves a closer look at native libraries and process behavior.

Common mistakes

• “heapUsed is all process memory.” It is only V8-managed JavaScript heap use; RSS is broader.
• “A Buffer cannot cause memory pressure.” Buffer payload bytes are external, but they still raise process memory.
• “The heap flag equals the container limit.” The process needs headroom beyond old space.
• “A larger heap fixes the bug.” It can postpone a crash while an unbounded collection continues growing.
• “A heap snapshot shows every native byte.” It focuses on V8 heap objects, not all RSS categories.

The useful contrast is simple. Heap tools explain retained JavaScript objects. Process counters explain broader pressure. You often need both: a snapshot to find a retained array and RSS plus external counters to understand a binary-heavy service.

Practice exercises

const bytes = new TextEncoder().encode("tea");
console.log(bytes.length);

const containerMB = 128;
const heapMB = 64;
console.log(containerMB - heapMB);

const cache = new Map();
cache.set("first", "tea");
cache.set("second", "milk");
cache.delete("first");
console.log(cache.size);

Check your understanding

Use the counters as categories, not as magic numbers. Then choose a bounded workload and a tool that can test your first guess.

Key takeaways

• V8 heap limits constrain managed JavaScript heap, not all process memory.
• Set old-space below a container limit so RSS has room for external and native memory.
• Read rss, heapTotal, heapUsed, external, and arrayBuffers together over a workload.
• Buffers commonly raise external and arrayBuffers far more than heapUsed.
• Snapshots explain retained heap objects; process counters explain broader memory pressure.
• For an OOM, find the growing collection or workload before simply raising a limit.

Coming next: How promises work inside, where reaction records and jobs explain why promise callbacks run later.