PM2 cluster worker never signals readiness after reload

Direct answer

When a PM2 cluster worker does not signal readiness during pm2 reload, PM2 does not infer health from CPU or memory. It starts a listen_timeout timer—30000 ms by default in current PM2 releases, though you should verify against your installed version—and waits for one of two IPC events: the Node.js 'listening' event emitted when a net.Server binds, or an explicit process.send('ready') message when wait_ready is enabled. If neither arrives before the timer expires, PM2 marks the replacement worker as failed and rolls back to the previous process set. The timeout is a hard ceiling, not an adaptive check: PM2 will not abort earlier unless the worker exits on its own or kill_timeout forces termination.

Signal sequence and timeout interaction

The reload lifecycle follows a fixed order:

1. PM2 sends SIGINT or SIGTERM to the old worker and waits up to kill_timeout for a graceful exit.
2. Once the old worker is gone, PM2 forks the replacement.
3. The replacement must emit 'listening' or 'ready' within listen_timeout.
4. If the timer expires first, PM2 treats the start as failed and initiates rollback.

Shutdown hooks on the old worker affect step 1 only. They do not shorten or extend the readiness window for the new worker.

Tuning listen_timeout

listen_timeout can be shortened in an ecosystem file or via the CLI. Lowering it makes rollback happen sooner, but it does not create an early-abort path for a worker that is merely slow to initialize.

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'api',
    script: 'server.js',
    instances: 2,
    exec_mode: 'cluster',
    listen_timeout: 8000,
    kill_timeout: 5000,
    wait_ready: true
  }]
}

You can also override per invocation: pm2 reload api --listen-timeout 8000.

Recommended readiness pattern

To keep reloads fast while avoiding false failures:

• Perform heavy initialization before calling server.listen(), and keep that work asynchronous so the event loop is not blocked.
• If you rely on net.Server, no extra code is needed—the 'listening' event fires automatically when the socket binds.
• If you use wait_ready, send the ready message in the listen callback:

const server = require('http').createServer(app);
server.listen(3000, () => {
  process.send('ready');
});

• Keep shutdown handlers short. They govern how quickly the old worker exits under kill_timeout; they do not affect the readiness timer for the new worker.

Verification

To confirm the behavior locally, start a minimal app that never signals readiness and observe the rollback:

pm2 start app.js -i 2 --listen-timeout 3000
pm2 reload app
pm2 logs

You should see the reload stall for roughly the configured interval, then PM2 restores the previous workers. Adding process.send('ready') after listen and enabling wait_ready should make the same reload complete in seconds.

Caveat

One caution: a very low listen_timeout can cause false failures for applications that legitimately need extra startup time, turning a slow reload into a repeated rollback loop. Size the timeout to your worst-case initialization, not your average case.