How to Diagnose and Fix “JavaScript heap out of memory” Errors in Node.js

The "JavaScript heap out of memory" error means your Node.js process tried to use more memory than V8 allows, and crashed. There are two responses: a quick stopgap to get running again, and the real fix — finding why your app wanted so much memory. Do both, in that order.

The quick stopgap: raise the heap limit

You can increase V8's heap limit with a flag:

node --max-old-space-size=4096 app.js

That allows up to 4 GB. It gets you running again, but treat it as buying time — if the app genuinely needed more, fine; if it is leaking, you have only delayed the crash.

Is it a leak or a genuine need?

• A leak — memory climbs steadily and never recovers until the crash. See profiling and fixing memory leaks.
• A genuine spike — a specific operation loads too much at once, like reading a huge file into memory or processing a massive array.

Fixing a genuine spike

• Stream large data instead of loading it whole — see Node.js streams.
• Process in batches rather than all at once.
• Avoid holding huge datasets in memory when you can page through them.

Fixing a leak

Capture and compare heap snapshots to find what keeps growing, then break the reference — unbounded caches, accumulating event listeners and uncleared timers are the usual causes.

On a small server

If your server simply has little RAM, a swap file can prevent hard crashes, and moving to more memory may be the honest answer — see upgrading your plan.

Frequently asked questions

Will raising --max-old-space-size fix it for good?

Only if the app legitimately needed more memory. If it is leaking, a higher limit just delays the crash. Always check whether memory keeps climbing before settling for a higher limit.

Why does it crash only under load?

Load multiplies memory use — more concurrent requests, bigger buffers, more cached objects. Load-test to reproduce it, then profile to see whether it is a leak or a legitimate peak you must design around.

Does the error mean my whole server is out of memory?

Not necessarily — it is V8's heap limit for that process, which can be lower than the machine's RAM. But on a tiny server, low system memory makes it worse. Check both.