Node.js "JavaScript heap out of memory" Fix and Diagnosis

V8, the JavaScript engine in Node.js, caps the size of its managed heap. When live objects approach that cap and garbage collection cannot free enough, Node prints this fatal error and aborts.

<--- Last few GCs --->
[1234:0x5f1a2b0]    48213 ms: Mark-Compact 2038.4 (2085.1) -> 2037.9 (2085.6) MB, 812.3 / 0.0 ms ...

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
 1: 0xb7a4e0 node::Abort() [node]

Older versions print CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory. The numbers in the "Last few GCs" lines show heap use right before the crash: if they sit near the limit and barely drop after Mark-Compact, memory is genuinely held.

Decision order

1. Is this a short-lived task (build, script, test run) or a long-running server?
2. For a build or script that processes lots of data, raising the limit is a legitimate fix.
3. For a server whose memory climbs steadily, you probably have a leak. A higher limit only delays the crash.
4. Check whether a container or the host kills the process before V8 would (exit 137, not this error).

Step 1: raise the limit (short tasks)

The flag is --max-old-space-size, in MiB. The Node.js docs advise leaving room for the rest of the system; on a machine with 2 GiB they suggest around 1536.

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

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

The default limit depends on your Node version and the memory available, so do not assume a fixed number. You can print the effective limit:

node -e "console.log(Math.round(require('v8').getHeapStatistics().heap_size_limit/1048576)+' MiB')"

Never set the value above the memory you actually have: the OS or the container runtime will then kill the process instead (see below).

Step 2: find what is eating memory

Capture a heap snapshot when memory nears the limit; the Node docs describe a flag that writes snapshots automatically:

node --max-old-space-size=512 --heapsnapshot-near-heap-limit=3 server.js

Open the .heapsnapshot file in Chrome DevTools (Memory tab) and sort by Retained Size. Take two snapshots some minutes apart and use the Comparison view to see what grows. You can also inspect a running process with node --inspect and DevTools.

Frequent real-world causes:

• Unbounded caches. A plain object or Map used as a cache with no eviction. Use an LRU with a size cap.
• Listeners that never detach. emitter.on(...) added on every request. Node warns MaxListenersExceededWarning; do not silence it, fix it.
• Reading whole files or query results into memory. Stream instead: fs.createReadStream, database cursors, stream.pipeline.
• Huge JSON. JSON.parse on hundreds of megabytes briefly needs several times the size in memory.
• Global arrays collecting logs or metrics forever.
• Closures holding large objects, such as a request object captured by a timer.
• Per-request state stored in module scope.

See the glossary entry on memory leaks.

Step 3: build tools

Bundlers, TypeScript, and test runners hit this on big projects. Options: raise the limit as above in CI, split the build, disable source maps in production builds, reduce the number of parallel workers (each worker has its own heap), and upgrade the tool. A bloated bundle is often the symptom of a heavy dependency; use the पेज वेट एनालाइज़र to see what your site ships after the build.

Step 4: containers and process managers

V8's heap limit is separate from the cgroup memory limit. If your container has 512 MiB and V8 is allowed more, the kernel kills the process with SIGKILL and you see exit code 137 and no V8 message. Set the heap lower than the container limit, leaving headroom for buffers, native memory and the stack. See Docker exit code 137 and Kubernetes CrashLoopBackOff. Remember that Buffer and typed array memory lives outside the V8 heap, so total resident memory can exceed --max-old-space-size.

Step 5: operate defensively

• Track memory in production: process.memoryUsage().heapUsed and RSS, exported to your metrics system.
• Restart workers on a schedule or at a memory threshold as a stopgap while you hunt the leak, but do not treat it as a fix.
• Put a health endpoint under an uptime monitor so an out-of-memory restart loop reaches you quickly.

अगले कदम

• Check overall health with the वेबसाइट हेल्थ चेक.
• Measure payload with the पेज वेट एनालाइज़र.
• Read Docker website down checklist.
• Learn about memory leaks.

सामान्य प्रश्न

What is the default heap size?

It depends on the Node version and the machine's memory, so print heap_size_limit as shown above rather than relying on a number you read somewhere.

Is --max-old-space-size safe for production?

Yes, if you set it below the container or machine memory. It does not fix leaks, only moves the failure later.

Why do I see exit 137 and no V8 message?

The kernel's out-of-memory killer ended the process before V8 hit its own limit. Raise the container limit or lower the heap.

Does adding swap help?

It can prevent a kill but makes garbage collection extremely slow. Fix the memory use instead.

यह पेज सामान्य जानकारी है, जिसे हमारी संपादकीय टीम ने लिखा है और दस्तावेज़ीकरण बदलने पर अपडेट किया जाता है। सर्वर और प्रदाता अलग-अलग होते हैं, इसलिए बदलाव पहले सुरक्षित तरीके से जाँचें। देखें: संपादकीय नीति और अस्वीकरण.