PM2 Cheatsheet - Node.js Process Manager Reference

SymptomAfter a reboot every process is gone and pm2 list is empty.

Causepm2 startup only prints a command to run; if that line was never executed as the right user the boot unit is not installed, and the list stored by pm2 save has nothing to restore it from.

FixRun pm2 save to store the list, then execute the line that pm2 startup prints, and confirm with pm2 resurrect.

SymptomI edited the config but the old values keep running no matter how often I restart.

CauseThe process still carries its launch-time arguments; the newly added keys were never read. It is also possible the launch used --env and picked up a different section.

FixCheck the effective start command and environment with pm2 describe api, then relaunch from the config with pm2 start ecosystem.config.js --env production.

SymptomThe process restarts by itself after a while and the restart count keeps climbing.

CauseMemory crossed the max_memory_restart ceiling and PM2 restarted it on purpose; the backstop is working, the process did not crash on its own.

FixConfirm with pm2 show api by reading restart count and memory, then hunt the accumulating allocation in code; pm2 reset api clears the counter so it stops polluting the picture.

SymptomThe port is clearly listening locally yet the service is intermittently unreachable.

CauseWith multiple instances started via -i each one tries to bind the same port; the first takes it and the rest restart on the conflict while the list still shows them as present.

FixCheck instance count against port binding, and for multiple instances move to cluster mode via exec_mode: "cluster" in the config, then verify the count in pm2 list.

SymptomLogs filled the disk and the service died.

CauseThe default log files grow without bound; with neither rotation nor cleanup in place, once the disk fills the process can no longer write and falls over.

FixRun pm2 flush to reclaim space, then pm2 install pm2-logrotate for rotation, and pin error_file and out_file in the config when fixed locations matter.

SymptomThe restored process list points at an old code location.

Causepm2 save records the start command and working directory as they were; after the code moved or changed version, resurrect still launches from the recorded path.

FixCheck the paths in pm2 list after restoring, and if they disagree remove the stale entry with pm2 delete api and start again from the current config.

SymptomAuto restart fires constantly and the process never stays up.

CauseThe watch scope includes dependency and log directories, so writing a log or cache at runtime counts as a change and produces a start-write-restart loop.

FixKeep watch: true but state ignore_watch: ["node_modules", "logs"] in the config so triggers land only on real source edits.

SymptomThe pm2 panel opens and immediately exits without showing anything.

CauseThe live panel redraws the screen continuously and cannot render in a non-interactive session or when output is redirected.

FixSwitch to one-shot output: pm2 list for the overview, pm2 show api for one process memory and restart count.

SymptomThe restart count is polluted by an old failure and no longer says whether the current deployment is stable.

CauseThe counter accumulates across the process lifetime, so an early crash stays in it and the number cannot separate history from now.

FixAfter deploying, run pm2 reset api to zero the counter and watch pm2 monit to see whether it climbs again.