heap out of memory 🟩 Node.js

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

The V8 heap hit its limit — a large build (webpack, tsc, Next.js) needs more memory, or the app leaks.

Seen on: Node.js npm

Meaning

Node caps the heap (roughly 2–4 GB depending on version and system memory). Builds of large projects and memory leaks in long-running servers both hit it.

Common causes

  • Large frontend/TypeScript builds
  • Memory leak (growing caches, listeners, global arrays)
  • Loading huge JSON/files into memory
  • Container memory smaller than the heap limit

⚡ Quick fix

  1. Raise the heap: NODE_OPTIONS=--max-old-space-size=4096
  2. Stream large files instead of reading them whole
  3. Take heap snapshots to find leaks
  4. Keep the heap limit below the container limit

Detailed fix by platform

Node.js

  1. Raise heap for a build:
    bash
    NODE_OPTIONS=--max-old-space-size=4096 npm run build
node --inspect app.js     # then Chrome DevTools → Memory → heap snapshots to find leaks

How to diagnose

  1. Phase — Build or runtime?
  2. Growth — Memory grows steadily (leak) or spikes?
  3. Limits — Heap vs container memory

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.