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:

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

Sometimes, it also has alternative error message like this:

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

Both errors occur when JavaScript has many processes to handle, and the default memory allocated by Node is insufficient 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 version, 15, still has a limit below 2GB.

Solve JavaScript heap out of memory error

Add the --max-old-space-size option when running your npm command to fix the JavaScript heap out-of-memory error.

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

bash
1node --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:

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

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

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

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

Set Node memory limit using the 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:

bash
1export NODE_OPTIONS=--max_old_space_size=4096 #4GB

When using ZSH, 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.

Disable generate source map

Disabling source map generation (generate source map=false) during the build process can help reduce memory usage, especially if your project has many files or large source maps.

To disable source map generation in a Create React App project (assuming you're using react-scripts), you typically set the GENERATE_SOURCEMAP environment variable to false before running the build script.

You can do this directly in the terminal before running the build command:

bash
1GENERATE_SOURCEMAP=false npm run build

Or, if you're running the build script directly:

bash
1GENERATE_SOURCEMAP=false node --max-old-space-size=4096 ./node_modules/.bin/react-scripts build

By setting GENERATE_SOURCEMAP=false, you're instructing react-scripts not to generate source maps during the build process. This can help reduce memory usage and speed up the build, especially for large projects. However, remember that disabling source maps means you won't have source maps available for debugging in production, so use this option carefully, depending on your needs.

Why does the JavaScript heap go out of memory?

Before the creation of Node, JavaScript’s role in web development is limited to manipulating DOM elements 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 that allowed you to run complex database queries and other heavy processing before sending data back to the front end.

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

Many modules downloaded from npm depend 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.