Fixing "JavaScript Heap Out of Memory" in Node.js

Learn what causes the Node.js FATAL ERROR: Ineffective mark-compacts near heap limit crash and how to fix it by raising the heap size or fixing memory leaks.

Published September 16, 2026

'JavaScript heap out of memory' means Node's V8 heap hit its size limit. Raise the limit with --max-old-space-size as a quick fix, then find and fix the real leak or oversized data.

The concept

V8 limits the old-generation heap (roughly 2–4 GB by default depending on version and system). When live objects exceed it, the process aborts.

Causes: loading a huge file or query result into memory, unbounded caches or arrays, listeners never removed, and closures holding big objects.

Raise the limit, then investigate

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
node --max-old-space-size=4096 app.js
node --inspect app.js # open chrome://inspect → Memory

Practical examples

Set the limit for npm scripts

NODE_OPTIONS=--max-old-space-size=4096 npm run build

Stream instead of loading everything

import fs from 'fs'
import readline from 'readline'
const rl = readline.createInterface({ input: fs.createReadStream('big.csv') })
for await (const line of rl) handle(line)

Bound a cache

const cache = new Map()
function set(k, v) { cache.set(k, v); if (cache.size > 1000) cache.delete(cache.keys().next().value) }

Watch memory

setInterval(() => console.log(process.memoryUsage().heapUsed / 1e6 + ' MB'), 5000)

Common mistakes

  • Only raising the limit and never fixing the leak.
  • Setting it above the machine's physical RAM.
  • Parsing a giant JSON in one go.

Key takeaways

  • Raise --max-old-space-size to unblock.
  • Stream large data.
  • Take heap snapshots to find leaks.

FAQ

What is the default limit?

It depends on Node version and system memory, typically about 2–4 GB.

Does this affect build tools?

Yes, large webpack or Next.js builds often need NODE_OPTIONS set.

More JavaScript articles