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
| Pattern | Next step |
|---|---|
| Whole files loaded into memory | Stream or bound file size |
| Too many simultaneous jobs | Reduce concurrency and queue excess work |
| Cache grows without bound | Add explicit size and retention limits |
| Build uses more memory than runtime | Investigate build resources separately |
| Baseline exceeds plan allowance | Reconcile 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.