Skip to content

Troubleshooting · By Rivtor · Updated

Fix Node.js heap out of memory in a container

Distinguish a V8 heap exhaustion error from a container being terminated for total memory use. Measure heap, external buffers, process RSS and concurrent work against the container limit before changing heap flags or upgrading resources.

See the Rivtor deployment workflow →

Classify how the process stopped

A JavaScript heap error and an operating-system memory kill are different boundaries. The V8 heap is part of total process memory; buffers, native allocations, thread stacks and other processes also consume the container budget. A large heap allowance can still leave too little room for the rest of the runtime.

Capture the exit signal or status, last sanitized error and container memory observation. Do not infer the cause from a gateway error alone; the proxy may simply see that the upstream disappeared.

Measure a representative workload

This illustrative diagnostic fragment reports numeric counters without dumping application records:

const usage = process.memoryUsage();
console.log({ rssBytes: usage.rss, heapUsedBytes: usage.heapUsed, externalBytes: usage.external });

Compare repeated observations at idle, during work and after work completes. A rising baseline after many identical requests can indicate retained objects, but one high reading is not enough to establish a leak.

Match the fix to the allocation

PatternNext step
Whole files loaded into memoryStream or bound file size
Too many simultaneous jobsReduce concurrency and queue excess work
Cache grows without boundAdd explicit size and retention limits
Build uses more memory than runtimeInvestigate build resources separately
Baseline exceeds plan allowanceReconcile requirements with available memory

Heap snapshots can contain secrets and customer data. Collect them only in an appropriate environment and keep them private. A snapshot is not ordinary public support material.

Verify within the actual resource boundary

On Rivtor, inspect current plan limits and the number of services sharing the relevant allowance. Do not change payment enforcement or plan configuration as a debugging shortcut.

Repeat the same bounded workload after a targeted change and check memory, latency and error rate. Include worker restarts and bursts. Set a heap limit only with an understanding of total memory needs; a flag cannot fix unbounded application allocation or make a smaller container contain more memory.

References