Solving the JavaScript Heap Out of Memory Error in JavaScript
How to fix FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
I recently came across this error whilst sorting out a client website, on build we were encountering a heap memory issue, the steps to resolve it are actually quite simple.
Running large JavaScript processes with Node.js can sometimes lead to an abrupt error that halts the execution. If you’ve encountered the dreaded message:
FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory
Or something like:
FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
You’re not alone. This happens when Node.js runs out of allocated memory during the execution of a process. The default memory limit Node.js sets for itself often isn’t sufficient when handling complex or large tasks. A common scenario where this occurs is during the build process with libraries like node-gyp, which can push memory limits past the default threshold.
Why Does This Error Happen?
Before Node.js existed, JavaScript was mostly confined to front-end work, dealing with the manipulation of DOM elements. But once Node.js arrived on the scene, it opened the door for JavaScript to run on the back-end, powering servers, processing database requests, and much more. This shift meant that JavaScript now handles much heavier tasks. Add in npm and its multitude of libraries and modules, and it’s easy to see how resource-heavy operations can trigger memory issues.
As you pull in more packages and dependencies—especially ones that require compilation, like node-gyp—memory usage balloons, sometimes beyond the default limits of Node.js.
How to Increase Node.js Memory Allocation
The solution to this problem is to increase the heap size by manually adjusting Node’s memory limit. You can do this by passing the --max-old-space-size option to Node.js when running commands. Here’s an example of how you can allocate 4GB of memory:
node --max-old-space-size=2048 index.js
If you’re facing the issue during an npm install, you can pass the option directly to npm:
node --max-old-space-size=2048 `which npm` install
Node’s memory size starts from 1024MB (1GB), and you can adjust it depending on the complexity of your process. Here’s a breakdown of the heap size options you can try:
• --max-old-space-size=1024 (1GB)
• --max-old-space-size=2048 (2GB)
• --max-old-space-size=4096 (4GB)
Permanent Solution: Set Memory Limit in Configuration
If you find yourself constantly running into this issue, you can set the memory limit permanently by adding it to your terminal configuration file.
For Bash users, add this line to your .bashrc:
export NODE_OPTIONS=--max_old_space_size=4096 # 4GB
If you’re using ZSH, you would instead add it to your .zshrc file.
Be Careful!
It’s important to note that while increasing the memory limit can solve the heap out of memory error, assigning too much memory can negatively affect your machine’s performance. Always check how much memory is available on your system before upping the allocation.
By understanding why this error occurs and how to adjust Node’s memory settings, you’ll be able to handle even the most memory-intensive JavaScript processes without interruptions.
If you’ve found this helpful, please subscribe and get the latest tech news, discussion, bug fixes, free code and more.