Zero‑downtime reload in PM2: practical steps, example, and trade‑offs

Zero‑downtime reload in PM2: why it matters

When a Node.js application restarts, all existing TCP or HTTP connections are terminated, which can cause users to experience timeouts or error pages. Zero‑downtime reload prevents that interruption by keeping connections alive while new code is loaded.

What is zero‑downtime reload?

PM2 creates a brand‑new worker process, then swaps the incoming traffic to it. The old worker receives a SIGTERM signal and is given a configurable grace period to finish any in‑flight requests before it exits. This coordinated approach lets the service stay online throughout the restart.

How PM2 coordinates the reload

PM2 keeps a map of each worker’s PID and works with Node’s cluster module to manage the restart sequence. It sends the termination signal to the appropriate worker, waits for the grace period, and only then removes the old process from the load balancer. Dashboard events and log entries let you see the progress in real time.

Grace period and SIGTERM

After sending SIGTERM, PM2 waits the duration set by the --stop-timeout option (default ten seconds). During this window the application can close sockets, flush buffers, and complete pending HTTP requests, ensuring a smooth hand‑off to the new worker.

Concrete example

1. Start a minimal Express server with PM2: pm2 start app.js --name demo. Verify the status is online using pm2 list. This command requires Node.js, PM2 installed globally or locally, and the executing user must have permission to run PM2 commands.
2. Trigger a reload: pm2 reload demo. Watch the status change from online to reloading and back to online. While this happens, you can run pm2 monit or hit a health‑check endpoint to confirm that no requests are dropped.
3. Examine the logs for the shutdown sequence. Look for a line containing SIGTERM followed by a message that the process exited after the configured grace period. If the old worker exits immediately, the grace period may be too short.

Trade‑off and limitation

• Memory consumption temporarily doubles because both the old and new workers run side‑by‑side until the old process terminates. On a host with limited RAM this can cause an out‑of‑memory (OOM) condition; you can mitigate it with --max-memory-restart or by reducing the number of workers.
• If the application ignores SIGTERM or does not close sockets promptly, the old worker may terminate abruptly, causing active connections to be dropped and resulting in a brief outage.
• In cluster mode, traffic is load‑balanced across all healthy workers. If a stale worker remains marked as online, it may still receive requests after the reload, which can lead to inconsistent behavior.
• Shared resources such as file handles, database connections, or in‑memory caches must be synchronized. A race condition can occur if the old process releases a resource while the new process is still initializing.

Actionable closing

To make zero‑downtime reload reliable in your project, follow these steps:

1. Implement a SIGTERM handler in your code that finishes pending work and closes network sockets before exiting.
2. Adjust the --stop-timeout or --grace-period setting in PM2’s configuration to match the longest request your app can take.
3. Monitor memory usage during the reload (for example with pm2 show demo) and be prepared to scale the instance or lower the worker count if you see a spike.
4. Verify the reload by checking a health‑check endpoint or running pm2 monit and confirming that the connection count stays steady.