A common problem while working on a JavaScript Node.js project is the “JavaScript heap out of memory” error. This error usually occurs when the default memory allocated by your system to Node.js is not enough to run a large project.

The error is common whether you run your project on Windows, macOS, or a Linux distribution like Ubuntu. Luckily, there are a few easy fixes that can help resolve the “JavaScript heap out of memory” or "reached heap limit allocation failed" error.

What Is Heap Memory?

Before you look at fixing the error, it's useful to understand what heap memory is and how programs use it.

shape of skull in computer code

Memory allocated on the system heap is also called dynamically allocated memory. It’s up to the programmer to use the available memory as they see fit. More importantly, the heap size for a program depends on the available virtual memory allocated to it.

If you’re running a relatively-large project, it may require more memory than the default allocated chunk. This may cause your project to crash and log the “JavaScript heap out of memory” error. The heap memory issue in Node.js can also be caused by an invalid page table size and issues with the function call stack.

The following error logs indicate heap memory issues within the Node.js runtime:

  • Reached heap limit allocation failed - javascript heap out of memory
  • Fatal error: call_and_retry_last allocation failed - javascript heap out of memory
  • Fatal error: ineffective mark-compacts near heap limit allocation failed - javascript heap out of memory
  • Fatal error: invalid table size allocation failed - javascript heap out of memory

How to Fix JavaScript Heap Out of Memory on Windows

Regardless of your IDE, the fix to “JavaScript heap out of memory” for the Node.js fix is identical.

You can add an environment variable through Control Panel to increase the memory allocated to a Node.js project.

  1. Open the Start menu, search for Advanced System Settings, and select the Best match.
  2. From the dialog box, click on Environment Variables, then click on New from either System variables or User variables. The former applies to all users on your computer, while the latter affects just your current account
  3. In the Variable name field enter NODE_OPTIONS. In the Variable value field enter --max-old-space-size=4096. This value will allocate 4GB of virtual memory to Node.js. To set a different value, multiply the amount you require in GB by 1024 (the variable value needs to be in MB).
    A Windows dialog showing a new environment variable with fields for name and value
  4. Click on OK to save your changes, then click Apply and finally click OK once more. Restart your project for the changes to take effect and you will no longer face the "JavaScript heap out of memory".

You can also set an environment variable through a Windows PowerShell terminal.

Launch a PowerShell terminal, type the below command and press Enter:

        $env:NODE_OPTIONS="--max-old-space-size=4096"
    

If you only want to increase the heap memory temporarily, run the below command in a PowerShell terminal before running your project:

        set NODE_OPTIONS=--max-old-space-size=4096
    

Once you’ve entered this command, you can deploy/run your project using npm run dev or your own script.

Remember always to enter the required memory size in MB. Not doing so can cause unexpected behavior in your program. It is also vital not to allocate your entire available memory as this can cause a significant system failure.

How to Fix JavaScript Heap Out of Memory Error on macOS and Linux

On macOS and Linux, the "JavaScript heap out of memory" fix is very similar. You should export an environment variable that specifies the amount of virtual memory allocated to Node.js.

In your terminal, before you run your project, enter the following command and press Enter:

        export NODE_OPTIONS=--max-old-space-size=4096
    

This will allocate 4GB of virtual memory to the execution space of Node.js. To set a different amount of memory, replace 4096 with the required amount in MB.

You can add the above command to your configuration file to avoid repeating the process. To do so, follow the same process for setting your PATH variable.

Avoid JavaScript Heap Out of Memory Error

You can avoid this error by ensuring your program is free of memory leaks. Proper memory management is crucial when writing your programs, especially in a low-level language.

While increasing the allocated memory will temporarily fix the problem, you should find the root cause and fix it.