Search guides

Fix Node that runs out of memory

We'll increase the heap with NODE_OPTIONS, check for leaks, and reduce memory use—or tell you when to escalate.

Troubleshooting · Devices & software
10–25 min
What you'll need
  • Terminal access
  • Ability to modify package.json or environment
Step 1 of 8

Quick triage — pick your path

Get started

Choose the option that matches what you see. You can jump straight to that section.

Show full guide

Steps

Goal: Fix Node out-of-memory errors by increasing the heap, setting NODE_OPTIONS for builds, or addressing leaks.

  • Check the error. “JavaScript heap out of memory” or “Reached heap limit” means the V8 heap limit was hit.
  • Good: You see the heap error. Proceed to Increase heap.
  • Bad: Different error—see a different guide.

Increase heap

Goal: Raise the V8 heap limit with NODE_OPTIONS.

  • For a one-off command: NODE_OPTIONS=--max-old-space-size=4096 node your-script.js (4096 = 4GB).
  • For npm run build: NODE_OPTIONS=--max-old-space-size=4096 npm run build.
  • Or export in the shell: export NODE_OPTIONS=--max-old-space-size=4096, then run the command.
  • Confirm you should see the process run without the heap error.
  • Bad: Still fails—try 8192 (8GB) or check Set for npm scripts.

Set for npm scripts

Goal: Make NODE_OPTIONS apply to npm scripts (build, test, etc.).

  • Edit package.json. Add NODE_OPTIONS to the script: "build": "NODE_OPTIONS=--max-old-space-size=4096 vite build" (or webpack, etc.).
  • Or create a .env file: NODE_OPTIONS=--max-old-space-size=4096. Some tools load .env automatically.
  • Confirm you should see the build use the larger heap.
  • Bad: Still fails—check if Node is 32-bit: node -p "process.arch". If ia32, install 64-bit Node.

Check for leaks

Goal: Determine if the process leaks memory.

  • Restart the process. Watch memory with ps aux or top (sort by MEM).
  • When memory grows steadily over time, there is a leak. Restarting is a workaround; profiling fixes the cause.
  • Confirm you should see memory stabilize or grow.
  • Bad: Memory spikes quickly—may need a larger heap or workload optimization.

When to get help

Escalate if:

  • Increasing the heap does not help.
  • The process leaks and you cannot fix the code.
  • The workload needs more than ~8GB heap.

Provide the error, NODE_OPTIONS used, and memory usage over time.

Verification

  • The Node process or npm script runs without “JavaScript heap out of memory.”
  • NODE_OPTIONS=--max-old-space-size=4096 (or your value) is set when needed.
  • Builds complete successfully; long-running processes do not crash from heap limit.

Escalation ladder

Work from the device outward. Stop when the problem is fixed.

  1. Increase heap NODE_OPTIONS=--max-old-space-size=4096 (or higher).
  2. Set for npm scripts Add NODE_OPTIONS to build script or .env.
  3. Restart or reduce memory Restart leaky processes; reduce build parallelism.
  4. Escalate Provide error, NODE_OPTIONS, memory usage over time.

What to capture if you need help

Before calling support or posting for help, have these ready. It speeds everything up.

  • Full error message
  • NODE_OPTIONS value used
  • process.arch (32- or 64-bit)
  • Memory usage over time (if leak suspected)
  • Steps already tried

Do you see "JavaScript heap out of memory" or "Reached heap limit"?

The V8 heap has a default limit. Large builds or data can hit it.

Check the error message. Good: heap out of memory or Reached heap limit—proceed to increase heap. Bad: Different error (EACCES, crash)—different guide.

Yes No

You can change your answer later.

Is it a one-off command or an npm script?

One-off: use NODE_OPTIONS in the same line. npm script: add to the script or .env.

One-off: `NODE_OPTIONS=--max-old-space-size=4096 node script.js`. npm script: add `NODE_OPTIONS=--max-old-space-size=4096` to the script in package.json or set in .env. Good: command or build runs. Bad: still fails—try higher value (8192) or check for leaks.
Question

One-off or npm script?

Continue

You can change your answer later.

Does it work after increasing the heap?

Retry with NODE_OPTIONS=--max-old-space-size=4096 or higher.

Retry the command or build with the larger heap. Good: succeeds. Bad: still fails—check if 32-bit Node (node -p process.arch), try 8192, or check for memory leak.

Yes No

You can change your answer later.

Does memory grow over time before the crash?

A leak causes steady memory growth until the limit is hit.

Restart the process and watch memory with ps aux or top. Good: memory grows steadily—leak; restart as workaround, profile to fix. Bad: memory spikes quickly—may need more heap or optimize the workload.

Yes No

You can change your answer later.

Restart and monitor

Restart the process. Use systemd, PM2, or cron to restart periodically. For a proper fix, profile with --inspect and Chrome DevTools or clinic.js.

Done

Resolved

The process runs with the increased heap. Consider optimizing if you need more than 4–8GB.

Done

Escalate

Provide the error, NODE_OPTIONS used, process.arch, and memory usage. Escalate if increasing heap does not help or the workload needs more than ~8GB.

Done

Different error

EACCES, crashes, or other errors need a different guide. Check fix-npm-fails-with-permission or fix-out-of-memory-error-on-server for related problems.

Done

Reviewed by Blackbox Atlas

Frequently asked questions

Why does Node run out of memory?
The V8 heap has a default limit (~2GB on 64-bit). Large builds, big data, or memory leaks can hit it. Increase with NODE_OPTIONS=--max-old-space-size or fix the leak.
Can I fix Node out-of-memory myself?
Yes. Set NODE_OPTIONS=--max-old-space-size=4096 (or higher) before running Node. For npm scripts, add it to the script or .env. Restart leaky processes; profile if the leak persists.
When should I escalate Node memory issues?
If increasing the heap does not help, the process leaks and restarts do not fix it, or the workload needs more than ~8GB heap. Provide the error, NODE_OPTIONS used, and process memory over time.

Rate this guide

Was this helpful?

Continue to