Fatal Error: Reached Heap Limit Allocation Failed - JavaScript Heap Out Of Memory

What is the JavaScript "heap out of memory" error?

A heap is a region of a computer's memory where programs can store and manage data dynamically. This means the program can request memory from the heap and release it when it's no longer needed. It’s a crucial and flexible memory area used to store data that can vary in size and must be managed dynamically throughout a program's execution.

The "Fatal Error: Reached Heap Limit Allocation Failed - JavaScript Heap Out Of Memory" error occurs when a JavaScript application, typically running in a Node.js environment, tries to allocate more memory than is available on the heap. This leads to the application running out of memory, causing the process to crash.

What causes the JavaScript “heap out of memory” fatal error?

By default, the maximum heap size in Node.js depends on the version and platform. Older versions (up to 11.x) defaulted to 700 MB on 32-bit and 1,400 MB on 64-bit systems. In current LTS releases (Node.js 20.x and 22.x), the default is significantly higher – approximately 4 GB on 64-bit platforms, though the exact value scales based on available system RAM. In memory-constrained environments like small VPS instances or containers with low limits, the effective default will be lower. Therefore, if your application exceeds this limit, you’ll run into the "heap out of memory" error. But why does this happen? There are several factors:

• Large data structures. Collections of data that occupy a significant amount of memory during their execution can cause memory issues. These can be massive arrays with many elements, complex objects with many properties, or large files and datasets like images, videos, JSON, or CSV files.

• Memory leaks. A memory leak occurs when a program allocates memory during execution but fails to release it when it's no longer needed. It must be noted that it can be done unintentionally, especially in languages like JavaScript that release unused memory automatically. However, if objects are kept in memory by lingering references (such as global variables or event listeners), they won’t be garbage collected, leading to a memory leak. If you suspect a memory leak is behind the error, you can confirm it by running your application with the --inspect flag (node --inspect your-script.js) and opening Chrome DevTools. Take heap snapshots at intervals under the Memory tab – if memory usage keeps climbing between snapshots without dropping back down, you have a leak.

• Inefficient code. Algorithms or functions that use more resources than necessary to accomplish a task. The importance of efficient code might not always be clear to beginners or even advanced programmers, but it can quickly lead to optimization issues or cause errors. Here’s an example:

Instead of using an array, the values are stored in an object. A method like this is very complicated for no reason and uses more computer resources than needed.

• Recursive functions. A function that calls itself to solve a problem. Recursion is a common technique used to break down complex problems into simpler, more manageable parts. For example, calculating the factorial of a number or traversing a tree data structure. Each time a recursive function calls itself, the current state of the function is pushed onto the call stack. Do this enough times, and you’re going to overload it, causing a stack overflow (that’s where the name of our favorite website comes from!). Here’s an example code that may cause this issue:

• High concurrent requests. In a server environment, these refer to multiple requests being handled at the same time. When a server receives a high number of requests at the same time, it can strain the server's resources. It’s like trying to answer multiple messages on Slack at the same time while getting pings from the group chat, while a colleague walks up behind you to ask a question, while you’re getting a phone call. Wowee.

In simple terms, the "heap out of memory" error occurs when you ask the computer to do more than it can. While computers are efficient and powerful in the modern age, they still have set limitations. Errors like these are simply there to prevent issues that could cause stability or damage to your machine.

How to fix the JavaScript heap out of memory error in Node.js

If you got this error and feel like you reached a dead end, don’t worry, as there are several solutions to this problem. All you need to do is enter a simple command that increases the memory limit or make a few adjustments to your code or the dataset. The following fixes apply to Node.js environments. For browser-side heap errors, use Chrome DevTools memory profiler.

Increase the memory limit

The most straightforward way to overcome this error is to simply increase the set memory limit. As mentioned before, Node.js has a memory limit of around 1.5 GB. You can increase this limit by passing the --max-old-space-size flag when running your Node.js application. This flag allows you to specify the maximum memory size (in megabytes) that Node.js can allocate. Make sure to set this to no more than 75% of your available system RAM:

Alternatively, if you don’t want to set the maximum size every time you run a script, you can export it as an environment variable:

The above commands allow you to run your script with a new memory limit of 5000 MB (5 GB). You can change the number to whichever value you desire, but take care not to go crazy with power and put stress on your computer. 

Keep in mind that the export command only applies to your current terminal session. If you close the window or run your build through npm run build or yarn build, the setting won't carry over. To make the memory limit persistent across your project's scripts, set it directly in your package.json:

{
 "scripts": {
   "build": "node --max-old-space-size=4096 node_modules/.bin/webpack",
   "start": "node --max-old-space-size=4096 your-script.js"
 }
}

{
 "scripts": {
   "build": "node --max-old-space-size=4096 node_modules/.bin/webpack",
   "start": "node --max-old-space-size=4096 your-script.js"
 }
}

This way, every developer on the team gets the same memory allocation without needing to remember environment variables, and it works consistently across npm, yarn, and CI pipelines.

Optimize your code

One of the best ways to avoid an issue is to not cause it in the first place. Seems logical enough, right? A clean and optimized code should be the standard for any self-respecting developer because it increases the application performance and avoids "heap out of memory" errors.

Here are a few suggestions to help you optimize your code:

• Minimize global variables. Global variables stay in memory the entire time the application is being used. If you have large objects or arrays stored globally, they might unnecessarily occupy memory even when they’re not in use. Therefore, instead of writing the code like this:

You can do it in a more optimal way:

• Identify memory hotspots. Identifying parts of your code that consume the most memory is crucial for optimization. You can start your Node.js application with the --inspect flag and use tools like Chrome DevTools to monitor memory usage and identify areas where memory consumption is abnormally high. You can then go back to those specific areas of your code and figure out how to make them more efficient.

• Offload processing to external services. Prevent the main application from running out of memory by delegating heavy lifting to other systems. For example, if your application needs to process large images or videos, use external services or APIs designed for such tasks. Services like AWS Lambda, Google Cloud Functions, or dedicated image processing services can handle these tasks without consuming your application's memory.

You probably can optimize your code in countless ways – we’ve named just a few of them. Always stick to best coding practices, write clean and efficient code, and perform regular audits. This way, you’ll avoid any issues that may arise.

Split large datasets

When working with large datasets, such as reading from a database or processing large files, loading all the data into memory at once can easily exhaust available memory. Instead, use pagination or batching to process smaller chunks of data sequentially.

Here’s an example of how you can use streams to process data in chunks Instead of loading an entire file or dataset into memory:

The above code ensures that the file is read and processed line-by-line instead of being loaded in its entirety. You can use this method to read certain lines from a file, perform various operations on them, and only then move to the next line without hogging up the heap memory.

You may also want to optimize the datasets that you have before they’re handled by your application. This includes cleaning the data, checking for duplicates, aggregating similar entries, or compressing it to take up less storage space. A neatly organized dataset can save you hours of trouble later down the line.

If you’re curious about where to obtain well-structured and easy-to-manage data for your project, check out Decodo's Scraping APIs. These APIs allow easy and unrestricted access to various websites, eCommerce pages, and search results from Google, Bing, and many more. The data can then be downloaded in widely supported CSV, JSON, table, or HTML formats, ensuring that management is simple and efficient.

Fix heap out of memory in webpack and build tools

The JavaScript heap out of memory error doesn't only happen at runtime. It's extremely common during build processes – Webpack, Next.js, Create React App, and Vite all trigger it regularly, especially on larger codebases.

The fix is the same --max-old-space-size flag, but applied through the NODE_OPTIONS environment variable so it covers whatever Node.js process your build tool spawns:

export NODE_OPTIONS="--max-old-space-size=8192" npm run build

export NODE_OPTIONS="--max-old-space-size=8192" npm run build

You can also set it inline for a single command:

NODE_OPTIONS="--max-old-space-size=8192" npx next build

NODE_OPTIONS="--max-old-space-size=8192" npx next build

Or add it directly to your package.json scripts so the whole team gets the same setting:

{   "scripts": {     "build": "NODE_OPTIONS='--max-old-space-size=8192' webpack --mode production"   } }

{   "scripts": {     "build": "NODE_OPTIONS='--max-old-space-size=8192' webpack --mode production"   } }

On Windows, use cross-env or set instead:

set NODE_OPTIONS=--max-old-space-size=8192 && npm run build

set NODE_OPTIONS=--max-old-space-size=8192 && npm run build

If increasing the memory limit alone doesn't solve it, the build configuration itself may be the problem. Generating full source maps (devtool: 'source-map') during development, running multiple webpack instances in parallel, or bundling massive dependencies without code splitting, all inflate memory usage unnecessarily. Consider switching to lighter source map options during development (eval-source-map), enabling incremental builds where supported, or moving to a less memory-intensive bundler like Vite for projects that allow it.

How to prevent the "fatal error: JavaScript heap out of memory" error in the future?

The best way to prevent the "heap out of memory" error from happening in your future projects is by proactively avoiding it. Here’s a summary of the above-mentioned tips to keep in mind:

• Increase the memory limit. By increasing the memory limit available to your Node.js process, you give your application more room to handle large datasets, complex operations, or high volumes of concurrent requests without crashing due to memory constraints.
• Optimize your code. Writing efficient code can significantly reduce memory usage, making your application less prone to hitting memory limits.
• Use clean datasets. Datasets that are cluttered with duplicates, irrelevant data, or inconsistencies can waste valuable memory and processing time. Clean datasets are leaner, more accurate, and easier to manage, reducing the likelihood of memory issues.

Final words

Encountering the "heap out of memory" error in JavaScript can be a daunting experience, but it also presents an opportunity to refine your approach to coding and memory management. You can significantly reduce the risk of running into this issue by increasing memory limits where necessary, optimizing your code to be more efficient, and ensuring that your datasets are clean and well-structured.

References

The following resources were referenced in compiling this guide:

JavaScript memory management

How to use the heap snapshot

How to collect big data

"You Don't Know JS (YDKJS)" by Kyle Simpson, 2020

"Clean Code: A Handbook of Agile Software Craftsmanship" by Robert C. Martin, 2008