node error: JavaScript heap out of memory during profiling - how to raise the heap limit

node error: JavaScript heap out of memory during profiling - how to raise the heap limit

TL;DR

The profiler's extra allocation pushed the process past the default heap limit (around 2GB on 64-bit). Raise it with --max-old-space-size, profile a shorter window, and sample less. If it still OOMs, take the profile from a heap snapshot instead of a live CPU profile.

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

Steps

1. Raise the heap limit for the profiled run: node --max-old-space-size=8192 app.js. Expected: The process gets headroom instead of dying at the default limit.

2. Shorten the profile window and lower the sampling rate; most of the OOM comes from the profiler buffering samples in-heap. Expected: Memory stays flat during the profile.

3. If you need allocation data specifically, capture a heap snapshot at the peak instead of a full allocation timeline. Expected: The snapshot shows the retainers without the live-profiling overhead.

4. Check whether the app itself leaks: compare heap-used after forced GC across runs (node --expose-gc). Expected: A leak shows growth independent of the profiler.

5. Set the flag in the real launch path (Docker CMD, systemd unit, PM2 config), not just your shell, so the next profile run inherits it. Expected: The setting survives restarts.

When to use

• Node dies with heap out of memory while a profiler is attached
• the crash happens only during profiling runs
• you need a bigger heap for a memory-heavy workload

When not to use

• the OOM happens without any profiler (that is an app leak, not a profiling problem)
• the error is 'allocation failed' in native code (check RSS, not the JS heap)
• you are on a 32-bit build (the heap ceiling is structural there)

Tool compatibility

• Node.js 16 through 22
• Chrome DevTools, clinic.js, 0x

Variant phrasings

• "node heap out of memory during profiling"
• "javascript heap out of memory profiler"
• "raise node heap limit max-old-space-size"

Why it happens

V8 caps the old-space heap (default roughly 2GB on 64-bit). Profilers allocate inside the same heap: sample buffers, instrumented closures, retained snapshots. A workload near the limit runs fine unprofiled and dies the moment the profiler's overhead lands on top.

Edge cases

• raising the limit on a container without raising the container memory limit just moves the OOM to the cgroup killer
• --max-old-space-size is in megabytes; 8192 means 8GB
• heap snapshots of a multi-GB heap can themselves take minutes to capture; plan the window

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_bSXsOgerV8yWO7WE290-vQ