Skip to main content

How to Solve the "FATAL ERROR: JavaScript heap out of memory" Error in Node.js in JavaScript

The FATAL ERROR: ... JavaScript heap out of memory error is a common issue in Node.js applications. It occurs when your Node.js process tries to use more memory than the default limit allocated by the V8 JavaScript engine. This often happens during memory-intensive tasks like building a large front-end application, processing large datasets, or running a server with a memory leak.

This guide will explain the two primary ways to solve this error by increasing Node.js's default memory limit: using the --max-old-space-size command-line flag and setting the NODE_OPTIONS environment variable.

The Core Problem: V8's Default Memory Limit​

Node.js is built on Google's V8 JavaScript engine, which has a default memory limit for the "old space" section of the heap, where long-lived objects are stored. This limit is typically around 2GB on a 64-bit system but can vary. When your application's memory usage exceeds this limit, the V8 garbage collector cannot free up enough space, and the process crashes to prevent further issues.

Solution 1 (Recommended): The --max-old-space-size Flag​

The most direct and common way to solve this error is to tell Node.js to increase this limit for a specific command using the --max-old-space-size flag. The value is specified in megabytes (MB).

For Running a Node Script​

If you get the error when running a script directly with node, add the flag before your script's name.

# Set the memory limit to 4GB (4096MB)
node --max-old-space-size=4096 your-script.js

For Running npm or npx Commands​

The error often occurs during a build step (e.g., npm run build) or when running a tool via npx (e.g., npx create-react-app). In these cases, you pass the flag to the node process that will execute the script.

# For an npm script (like a React build)
node --max-old-space-size=4096 ./node_modules/react-scripts/scripts/build.js

# For an npx command
# On macOS/Linux
node --max-old-space-size=4096 $(which npx) create-react-app my-app
# On Windows (using cross-env is easier, see below)

Making it Permanent with package.json​

Manually typing the flag every time is tedious. The best practice is to add it directly to the scripts section of your package.json file.

// package.json
{
  "scripts": {
    "start": "node --max-old-space-size=4096 server.js",
    "build": "node --max-old-space-size=8192 ./node_modules/react-scripts/scripts/build.js"
  }
}

Now, you can simply run npm start or npm run build, and the memory limit will be applied automatically.

Solution 2 (Advanced): The NODE_OPTIONS Environment Variable​

If you want to set the memory limit for all Node.js processes in your terminal session or even system-wide, you can use the NODE_OPTIONS environment variable. This is a more advanced approach.

Setting NODE_OPTIONS on macOS/Linux​

To set it for your current terminal session:

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

To make this setting permanent, add the line above to your shell's profile file (e.g., ~/.bashrc, ~/.zshrc, or ~/.bash_profile).

Setting NODE_OPTIONS on Windows​

In Command Prompt (CMD):

rem Sets the variable for the current session only
set NODE_OPTIONS=--max-old-space-size=4096

rem Sets the variable permanently for the user
setx NODE_OPTIONS "--max-old-space-size=4096"

In PowerShell:

# Sets the variable for the current session only
$env:NODE_OPTIONS="--max-old-space-size=4096"

You can also set this permanently through the "Environment Variables" panel in your advanced system settings.

How Much Memory Should You Allocate?​

There is no single correct answer, but here are some guidelines:

  • 4096 (4GB): A good starting point for most modern development machines and common build tasks.
  • 8192 (8GB): Often required for very large projects or complex builds.
  • Don't set it too high! You should leave enough memory for your operating system and other applications. A general rule of thumb is to not allocate more than 75% of your machine's total physical RAM.

If increasing the memory only delays the crash, you may have a memory leak in your application that needs to be debugged. Simply allocating more memory is a temporary fix, not a solution for a leak.

Conclusion​

The "JavaScript heap out of memory" error is a signal that your application's needs have exceeded Node.js's default limits.

  • The recommended best practice is to add the --max-old-space-size=VALUE flag directly to the relevant command in the scripts section of your package.json. This is explicit, project-specific, and works for all developers on the project.
  • Using the NODE_OPTIONS environment variable is a powerful alternative for setting a session-wide or system-wide default, but it is less portable.
  • Always be mindful of your system's total memory, and remember that if the error persists, you may need to investigate your code for a memory leak.

Table of Contents