Memory in Node.js

Memory in a Node process

Node runs JavaScript outside the browser, often on a server. A running Node program is called a process. The process needs memory for many things, not only your JavaScript objects.

Inside every Node process is V8. V8 is the engine that runs your JavaScript. V8 keeps your objects, arrays, and strings in an area of memory called the heap.

The process also holds memory outside the heap:

• Node's own built-in code.
• Raw bytes from files, the network, and images.
• Libraries written in other languages, such as C++.

So when memory grows, first ask which kind of memory is growing.

This lesson continues from Memory in large apps. That lesson asked whether an app keeps data for too long. A server has one more question: can the process stay under its memory limit while it handles real requests?

In this lesson you will:

• read the memory numbers that Node reports,
• choose a limit for the heap,
• save a picture of the heap to a file,
• read the message Node prints when the heap runs out.

These tools don't fix memory problems by themselves. They point you to the part of the code you need to look at.

Bytes before memory counters

A byte is the smallest unit of memory you will meet here. One letter like a takes one byte. Node reports memory as a count of bytes, so it helps to see one familiar amount first.

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

An ArrayBuffer is a block of raw bytes. It works in the browser too, so you can run this code here.

• Line 1 makes an ArrayBuffer with 1024 × 1024 bytes.
• Line 2 prints its length in bytes: 1048576.

1048576 bytes is one mebibyte (MiB). Many tools just call it one megabyte (MB). This lesson says MB too.

Server tools often show big numbers such as 10485760. To turn bytes into MB, divide by 1024 two times. 10485760 bytes is 10 MB.

Heap limits and containers

V8 does not let the heap grow forever. It has a heap limit: the most memory the heap may use. You can read the current limit with v8.getHeapStatistics().heap_size_limit.

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

• Line 1 loads node:v8, a module built into Node that reports on V8.
• Line 2 prints the heap limit in bytes.

This code works only in Node, so there is no Run button here. The lesson test runs it twice: once with a 32 MB limit and once with a 64 MB limit. It checks that the 64 MB run prints a bigger number.

You set the limit with a flag, an option you type after node when you start a program:

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

The number is in MB. "Old space" is the biggest part of the heap: the part where long-lived objects stay. So this flag caps the heap. It does not cap the whole process. The process can still use more memory for:

• Buffers and other raw bytes,
• Node's built-in code,
• stacks: the memory that tracks which functions are running right now.

Servers often run inside a container. A container is a sealed box for one app, and it has its own memory limit for the whole process. The step-through below works out how much room is left when the container allows 128 MB and the heap gets 64 MB.

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

In a container, set the heap limit below the container's limit. The gap between them is called headroom: room for everything that is not in the heap. Without headroom, the operating system may stop the whole process with no warning. Then you get no helpful message about the heap.

Reading process.memoryUsage()

process.memoryUsage() asks Node how much memory the process uses right now. It returns an object with five numbers. Each number is a counter for one kind of memory, in bytes. No single counter tells the whole story, so read them together.

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

• Line 1 asks Node for the counters right now.
• Line 2 prints the counter names, joined with commas. In Node it prints rss,heapTotal,heapUsed,external,arrayBuffers.

The table below explains each counter. Read each row as: "this counter measures this, and here is what to remember about it."

Two counters overlap. arrayBuffers is already counted inside external. So don't add those two together. You would count the same bytes twice.

Read the counters at clear moments: before a batch of work, after it, and again after the work should have been let go. Don't log them on every request. That makes a lot of noise, and the log strings use memory too. For a server that runs for days, save the same five counters every few minutes and watch the trend.

Buffers and external memory

A Buffer is Node's type for a block of raw bytes. You meet Buffers when you read files, receive data from the network, or work with images.

The bytes of a Buffer are not stored in the V8 heap. They live outside it. So a big Buffer makes external grow a lot, while heapUsed barely moves.

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 the counters before.
• Line 2 makes a Buffer of 10 MB. Buffer.alloc(n) makes a Buffer of n bytes, all set to zero.
• Line 3 saves the counters after.
• Line 4 prints the Buffer's size: 10485760 bytes.
• Lines 5 and 6 print whether external and arrayBuffers grew. Both print true.

The exact numbers are different on every computer. So the lesson test checks only facts that are always true: external grows by at least 10 MB, and heapUsed grows by much less.

The step-through below uses a small model with round numbers, so you can follow the change.

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 outside the heap, but the process still holds its bytes. So keep binary work small and limited:

• Limit how many uploads run at the same time.
• Don't keep every file in one big array.
• When a request ends, drop your links to its Buffers.

When your server handles a lot of files, watch rss and external together.

Heap snapshots in Node.js

A heap snapshot is a file that lists every object in the V8 heap at one moment, and what keeps each one alive. It is most useful in two cases:

• You compare a snapshot from before some work with one from after.
• You look for what still holds a list that should have been thrown away.

There are three ways to make one in Node.

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

• Line 1 loads the built-in node:v8 module.
• Line 2 writes the snapshot to a file and keeps the file's name.
• Line 3 prints that file name.

Making a snapshot pauses your program and needs extra memory. So only do it on purpose, on a machine where a pause is safe. To read the file, open it in the Memory panel of Chrome DevTools.

The second way uses a signal. A signal is a short message that you send to a running process from the terminal.

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

• Line 1 starts Node and tells it: "when you get the signal SIGUSR2, save a snapshot."
• Line 2 sends that signal. Put the process's ID number in place of <pid>.

This helps when you can't easily add code at the moment the problem happens. On a real server, follow your team's rules for sending signals to live processes.

The third way saves a snapshot just before the heap runs out:

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

This starts Node with a 64 MB heap limit. When the heap gets close to that limit, Node saves one snapshot. The snapshot is a clue for later. It does not stop the crash. To learn how to read it, go on to Heap snapshots in depth and look for what keeps the objects alive.

Diagnosing out-of-memory crashes

An out-of-memory crash (OOM for short) happens when the heap is at its limit and V8 has no room for the next new value. Node stops and prints a report. The report contains a line like FATAL ERROR: ... JavaScript heap out of memory.

Look for that phrase first. It tells you the heap was full. A container can also stop a process for other reasons, and then this phrase is missing.

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

• Line 1 makes the orders array. The array stays in use, so nothing in it can be thrown away.
• Line 2 starts a loop that never ends.
• Line 3 adds a long string to the array each time: the word "tea " repeated 10000 times.

Run code like this only in a separate test process with a tiny limit. The lesson test runs it with --max-old-space-size=32. It checks two things: the process ends with an error, and its output contains heap out of memory.

The table below lists common reasons a heap fills up. Read each row as: "this is the cause, this is what happens, and this is what to try first."

When you see an OOM report, follow these steps:

1. Check that the report says JavaScript heap out of memory.
2. Compare the heap counters and the external counter.
3. Make the crash happen again, with a small, safe limit.
4. Save a heap snapshot if you can.
5. Find the list or cache that keeps growing, and what holds it.

A bigger heap limit only makes the crash come later. If an array or cache grows forever, it will fill the bigger heap too.

A small server memory routine

Start with a memory budget:

1. Find out the container's memory limit.
2. Choose a smaller heap limit, and leave headroom.
3. Pick one piece of work to measure, such as one batch of uploads or one report. Read the counters before it and after it.

Then put a limit on everything that can grow:

• A cache needs a largest size, or a time after which old entries are removed.
• A big file should be streamed: read and handled one small piece at a time, instead of all at once.
• A server that accepts JSON needs a size limit for each request. Without one, a single huge request holds a huge string and all the objects parsed from it, both at the same time.

Watch for a trend, and connect it to one kind of work. Each trend points to a different place to look:

• heapUsed grows after every finished job: your code is probably keeping JavaScript objects it no longer needs.
• external grows while images are processed: too many Buffers are in use at the same time.
• rss grows, but the other two don't: look at libraries written in other languages and at Node itself.

Common mistakes

• "heapUsed is all the memory the process uses." It counts only the V8 heap. rss counts the whole process.
• "A Buffer can't fill up memory." A Buffer's bytes are outside the heap, but the process still holds them.
• "The heap limit should equal the container limit." The process needs headroom for memory outside the heap.
• "A bigger heap fixes the bug." It only makes the crash come later, while the array or cache keeps growing.
• "A heap snapshot shows every byte the process uses." It focuses on the objects in the V8 heap. Node's own code, the stacks, and much of the rest of rss are not in it.

Here is the short version. Heap tools explain which JavaScript objects are kept alive. The process counters show the memory of the whole process. You often need both. A snapshot finds the array that keeps growing. rss and external show how much a server that handles many files really uses.

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

For each question, first ask which kind of memory it is about: the heap, memory outside the heap, or the whole process.

Key takeaways

• The heap limit caps the V8 heap only, not the whole process.
• In a container, set the heap limit lower than the container limit. The gap is headroom for memory outside the heap.
• Read rss, heapTotal, heapUsed, external, and arrayBuffers together, before and after a piece of work.
• Buffers make external and arrayBuffers grow much more than heapUsed.
• A heap snapshot shows which objects are kept alive. The counters show the memory of the whole process.
• After an OOM, find what keeps growing before you raise a limit.

Coming next: How promises work inside. It shows the hidden records and the job queue that explain why promise callbacks run later.