How to solve JavaScript heap out of memory error

When running JavaScript process using Node, you may see an error that stops the running process.

The fatal error says JavaScript heap out of memory as seen below:

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

Sometimes, it also has alternative error message like this:

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

Both errors above occur when JavaScript has a lot of processes to handle, and the default allocated memory by Node is not enough to finish the running process.

An example of this error can be found when you have to build the packages you installed using npm install with the node-gyp library.

The default Node memory limit varies from version to version, but the latest Node version 15 still has a memory limit below 2GB.

Solve JavaScript heap out of memory error

To fix JavaScript heap out of memory error, you need to add the --max-old-space-size option when running your npm command.

Here’s an example of increasing the memory limit to 4GB:

node --max-old-space-size=4096 index.js

If you want to add the option when running the npm install command, then you can pass the option from Node to npm as follows:

node --max-old-space-size=4096 `which npm` install

If you still see the heap out of memory error, then you may need to increase the heap size even more. The memory size starts from 1024 for 1GB:

--max-old-space-size=1024 # increase memory to 1GB
--max-old-space-size=2048 # increase memory to 2GB
--max-old-space-size=3072 # increase memory to 3GB
--max-old-space-size=4096 # increase memory to 4GB
--max-old-space-size=8192 # increase memory to 8GB

Alternatively, you can also set the memory limit for your entire environment using a configuration file.

Set Node memory limit using configuration file

You can set the default memory limit using your terminal client’s configuration file.

If you’re using Bash, then add the following line to your .bashrc file:

export NODE_OPTIONS=--max_old_space_size=4096 #4GB

When you’re using ZSH, then add the line above to the .zshrc file.

Don’t forget to check the available memory in your machine before increasing the memory limit.

Too much memory allocated for Node may cause your machine to hang.

Why JavaScript heap out of memory occurs?

Before the creation of Node, JavaScript’s role in web development is limited to manipulating DOM elements in order to create an interactive experience for the users of your web application.

But after the release of Node, JavaScript suddenly had a back-end architecture, where you can run complex database queries and other heavy processing before sending data back to the front-end.

JavaScript also saw the rise of npm that allows you to download libraries and modules like React and Lodash.

Many modules downloaded from npm have lots of dependencies on other modules, and some may need to be compiled before they can be used.

Node memory usage will increase as you have more tasks to process. This is why JavaScript may have a heap out of memory error today.

Take your skills to the next level ⚡️

I'm sending out an occasional email with the latest tutorials on programming, web development, and statistics. Drop your email in the box below and I'll send new stuff straight into your inbox!

No spam. Unsubscribe anytime.