Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

PM2 does not restart my Node.js app after it crashes

Errorstatus errored in pm2 list

Short 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.

  • Applies to PM2 6, Node.js 22, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at the status column and the restart count for the app.

    pm2 status
  2. 2Match what you see, then jump to its fix

    1. 1status errored, with a restart count near 16The app crashes too fast and PM2 gives up (errored)Fix
    2. 2status stopped after a crash or a normal exit, and no restart count changeautorestart is turned offFix
    3. 3pm2 list is empty after a rebootThe server rebooted and PM2 itself did not come backFix

What does the error look like?

  • status errored in pm2 list
  • status stopped in pm2 list
  • the 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 --nostream

2Fix

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 status

Confirmed by pm2.keymetrics.io

Did this fix it?

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.js

2Fix

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 status

Confirmed by pm2.keymetrics.io

Did this fix it?

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 list

2Fix

Generate the startup script (run the command PM2 prints with sudo), then save the list.

pm2 startup
pm2 save

3Verify

Reboot and list the processes.

sudo reboot
pm2 status

Confirmed by pm2.keymetrics.io

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.