PM2 does not restart my Node.js app after it crashes
status errored in pm2 listShort answer
PM2 restarts a crashed process on its own, so a process that stays down has a reason. Check its status. Errored means it crashed too fast too often and PM2 gave up. Stopped means someone stopped it. A setting can also turn restarts off, and after a reboot PM2 needs a startup script.
Fix it fast
1Find out which cause you have
Look at the status column and the restart count for the app.
pm2 status2Match what you see, then jump to its fix
What does the error look like?
status errored in pm2 liststatus stopped in pm2 listthe app is gone from pm2 list after a server reboot
Cause 1 of 3
The app crashes too fast and PM2 gives up (errored)
1Check
PM2 counts restarts that happen less than min_uptime after start. After max_restarts of them in a row (16 by default) it marks the app errored and stops trying. A crash on start-up, such as a missing variable or port in use, causes this.
pm2 logs my-app --lines 50 --nostream2Fix
Fix the error in the log first. Then optionally add a restart delay with backoff, so a flapping app does not burn through its restarts, and start it again.
module.exports = {
apps: [{
name: "my-app",
script: "./server.js",
min_uptime: "10s",
max_restarts: 10,
exp_backoff_restart_delay: 100,
}],
};3Verify
Start the app from the file and check it stays online.
pm2 delete my-app
pm2 start ecosystem.config.js
pm2 statusConfirmed by pm2.keymetrics.io
Cause 2 of 3
autorestart is turned off
1Check
With autorestart set to false, or --no-autorestart on the command line, PM2 does not restart the app after it crashes or exits. This is meant for one-time scripts.
grep -n "autorestart" ecosystem.config.js2Fix
Remove the setting or set it to true, then start the app from the file.
// ecosystem.config.js
autorestart: true,3Verify
Kill the process on purpose and watch PM2 bring it back.
pm2 restart ecosystem.config.js
pm2 statusConfirmed by pm2.keymetrics.io
Cause 3 of 3
The server rebooted and PM2 itself did not come back
1Check
Crash restarts are done by the PM2 daemon. After a reboot nothing starts PM2 unless a startup script is installed and the process list was saved.
pm2 list2Fix
Generate the startup script (run the command PM2 prints with sudo), then save the list.
pm2 startup
pm2 save3Verify
Reboot and list the processes.
sudo reboot
pm2 statusConfirmed by pm2.keymetrics.io
How do I stop it coming back?
- Add a /health route and an external uptime check, so an errored app is noticed in minutes.
- Run pm2 save after every change to the process list.
- Use exp_backoff_restart_delay for apps that depend on a database that may be down for a short time.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
Related fixes
Servers
The shell cannot find pm2 after you installed it
bash: pm2: command not found
The shell found no pm2 file in any folder of PATH.
3 causes, each with a fixBack end
Node.js cannot start because the port is already taken
Error: listen EADDRINUSE: address already in use 127.0.0.1:8080
EADDRINUSE means another socket already listens on that port, so Node's listen() was refused.
4 causes, each with a fixBack end
process.env.NODE_ENV is undefined in a Node.js app
console.log(process.env.NODE_ENV) prints undefined
Node.js does not set NODE_ENV for you.
5 causes, each with a fixBack end
PM2 says the ecosystem file is malformated and refuses to start
Error [ERR_REQUIRE_ASYNC_MODULE]
PM2 prints 'malformated' whenever loading the config file throws.
3 causes, each with a fixBack end
Loading a .env file into a PM2 ecosystem config fails or gives undefined values
[PM2][ERROR] File ecosystem.config.js malformated
PM2 only passes the env block of the config to your app.
4 causes, each with a fixBack end
PM2 keeps the old environment variables after restart --update-env
the app still prints the old value after pm2 restart
A plain pm2 restart reuses the environment stored at first start.
4 causes, each with a fix