Node.js Reference ยท child_process, worker_threads and cluster
Node.js cluster.disconnect() method
Reference for cluster.disconnect() and worker.disconnect() in Node.js: stop accepting connections, let requests finish, exitedAfterDisconnect and rolling restarts.
cluster.disconnect([callback]) asks every worker to disconnect. A disconnecting worker closes the servers it shares through the cluster, so it stops accepting new connections; it then closes its IPC channel once those servers have finished closing (which means after their existing connections end). A worker with nothing else keeping it alive then exits by itself, without being killed.
That makes it the building block for a graceful shutdown or a rolling restart: connections already in progress finish, and new ones go to other workers. worker.disconnect() does the same for one worker.
import cluster from "node:cluster"; cluster.disconnect(() => { console.log("all workers disconnected"); });
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
cluster.disconnect(callback?: () => void): void worker.disconnect(): Worker
| Name | Description |
|---|---|
callback |
Optional. Called with no arguments (from the primary) when all workers have disconnected. |
Returns: cluster.disconnect() returns nothing. worker.disconnect() returns the worker, so calls can be chained.
Events: each Worker emits 'disconnect', and the cluster object re-emits it as cluster.on("disconnect", worker => ...). After the process ends, 'exit' follows. When the exit was a result of disconnect() (or kill()), worker.exitedAfterDisconnect is true.
Edge cases: a worker that keeps something alive besides cluster servers (an interval, an open database pool, a stdin listener) does not exit after disconnecting; it stays running with no IPC channel until you end it.
Usage notes
- Graceful, not abrupt. Unlike
worker.kill("SIGKILL")orprocess.exit(), disconnecting waits for open server connections to end. Long-lived connections (WebSockets, streams) can delay it indefinitely, so add a timeout that falls back toworker.kill(). exitedAfterDisconnectseparates crashes from deliberate stops. In an'exit'handler, only restart workers when it isfalse, otherwise a planned shutdown would trigger an endless restart loop.- In the worker,
cluster.worker.disconnect()(orprocess.disconnect()) disconnects itself, for example after catching a fatal error: stop taking new work, finish what is running, let the primary start a replacement. - Rolling restarts: fork a new worker, wait for its
'listening'event, then disconnect one old worker; repeat for each old worker so capacity never drops to zero. - Idle keep-alive connections are closed only when the HTTP server closes them. In Node 19 and later
server.close()also closes idle keep-alive connections; with long-lived busy ones, useserver.closeAllConnections()after a grace period. - Do not rely on
disconnect()alone for the primary's own exit. The primary exits when it has nothing left to do; clear its timers and listeners too. - The callback runs in the primary only. It tells you the IPC channels are closed; processes may still be finishing shutdown, so wait for
'exit'if you need to be sure they are gone.