How do I determine the correct "max-old-space-size" for node.js?

I'm having some trouble to understand how Node.js acts based on the parameter max-old-space-size.

In my case, for example, I'm running two t2.small AWS instances (2GB of RAM).

Not sure why, but I did set max-old-space-size=4096 (4GB). What does node do in this case? Could this configuration lead to a possible memory allocation failure?

How do I determine the correct value of max-old-space-size based on the server resources?

My application is constantly growing the memory usage and I'm trying to understand everything about node internals.


"Old space" is the biggest and most configurable section of V8's managed (aka garbage-collected) heap (i.e. where the JavaScript objects live), and the --max-old-space-size flag controls its maximum size. As memory consumption approaches the limit, V8 will spend more time on garbage collection in an effort to free unused memory.

If heap memory consumption (i.e. live objects that the GC cannot free) exceeds the limit, V8 will crash your process (for lack of alternative), so you don't want to set it too low. Of course, if you set it too high, then the additional heap usage that V8 will allow might cause your overall system to run out of memory (and either swap or kill random processes, for lack of alternative).

In summary, on a machine with 2GB of memory I would probably set --max-old-space-size to about 1.5GB to leave some memory for other uses and avoid swapping.


2020 Update

These options are now documented officially by node. For a 2GB machine, you should probably use:

NODE_OPTIONS=--max-old-space-size=1536

To determine the amount to use

You can see available memory on a Linux machine using free -m. Note that you can consider the total of the free and the buffers/cache memory as available, as buffers/cache can be thrown away instantly when needed (these buffers and cache are a nice way to use otherwise unused memory).

The official documentation formax-old-space-size also mentions:

On a machine with 2GB of memory, consider setting this to 1536 (1.5GB)

Hence the value above. Consider that the amount of memory needed for the base OS doesn't change much, so you could happily do 3.5 on a 4GB machine etc.

To notice the defaults and see the effect of changes:

The default is 2GB:

$ node

> v8.getHeapStatistics()
{
  ....
  heap_size_limit: 2197815296,
}

2197815296 is 2GB in bytes.

When set to 8GB, you can see heap_size_limit changes:

$ NODE_OPTIONS=--max_old_space_size=8192 node
Welcome to Node.js v14.17.4.
Type ".help" for more information.
> v8.getHeapStatistics()
{
  ...
  heap_size_limit: 8640266240,
  ...
}

As @Venryx mentions below you can also use process.memoryUsage()


This error occurs when the memory allocated for the executing application is less than the required memory. By default, the memory limit in Node.js is 512 MB. To increase this amount, you need to set the memory limit argument —-max-old-space-size. It will help avoid a memory limit issue.

node --max-old-space-size=1024 index.js #increase to 1gb
node --max-old-space-size=2048 index.js #increase to 2gb
node --max-old-space-size=3072 index.js #increase to 3gb
node --max-old-space-size=4096 index.js #increase to 4gb
node --max-old-space-size=5120 index.js #increase to 5gb
node --max-old-space-size=6144 index.js #increase to 6gb
node --max-old-space-size=7168 index.js #increase to 7gb
node --max-old-space-size=8192 index.js #increase to 8gb

https://medium.com/@vuongtran/how-to-solve-process-out-of-memory-in-node-js-5f0de8f8464c