Diagnosing Frequent PM2 max_memory_restart Triggers

PM2 logs showing repeated max_memory_restart every few minutes is a recognizable stability problem. The useful takeaway is that the restart is often a configuration mismatch or per-worker limit rather than a true leak, and the first step is to confirm actual memory use before changing thresholds.

Recognizable condition

Frequent restarts with messages referencing max_memory_restart, often correlated with short intervals between uptime. The service may appear healthy between restarts but never stabilizes.

Cause and diagnostic table

Ordered checks

1. Review PM2 logs for restart timestamps and memory usage. Run pm2 logs as the user who launched PM2. Look for max_memory_restart entries and note intervals.
2. Confirm actual consumption. Use pm2 monit for live metrics and cross-check with top or htop run with appropriate permissions. In code, log process.memoryUsage().rss periodically. Risk: adding logging increases overhead.
3. Verify the configured limit. Run pm2 show to view current max_memory_restart. Inspect ecosystem.config.js or CLI flags. PM2 v5 expects a string with unit, e.g., "200M". Syntax changed from v4.
4. Check versions and known issues. Note PM2 and Node.js versions. Inconsistent --max-old-space-size flags can override expectations.
5. Inspect cluster configuration. Check mode and instances in ecosystem.config.js. Remember the limit applies per worker.

Fixes tied to findings

Leak suspected

Profile the application and fix retention paths. Do not raise the threshold to mask growth.

Threshold too low

Increase max_memory_restart to match realistic peak usage with headroom, or remove it temporarily for validation. Edit ecosystem.config.js and reload with pm2 reload . Risk: higher limit delays restart on real leak.

Version or syntax issue

Upgrade PM2 and Node.js to a stable release and ensure the limit is expressed as a string with unit. Verify with pm2 show .

External pressure

Reduce co-located processes, enable pm2-logrotate to avoid large log files contributing to RSS, and isolate the service.

Cluster per-worker limit

Adjust instances or switch to fork mode if per-worker limits cause rapid restarts. Recalculate total memory budget.

Verification

• Run pm2 show to confirm the active max_memory_restart value.
• Use pm2 monit to watch memory and CPU after changes.
• Temporarily set max_memory_restart to null or a very high value and confirm restarts cease. Revert immediately after test.
• Correlate /var/log/pm2/pm2.log restart entries with system memory from free -m or top.

Escalation criteria

Escalate if restarts exceed five per minute, CPU spikes coincide with restarts, or the service becomes unavailable despite the checks above. Open an issue with PM2 version, Node version, ecosystem.config.js excerpt, and log timestamps.

Limitations and cautions

Node reported memory may differ from OS RSS. Cluster mode applies the limit per worker. Large unrotated logs can inflate memory. This guide assumes PM2 v5+ string syntax; verify current version before applying. Changes to memory limits alter failure mode, so test in a non-production environment first.