Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import cluster from "node:cluster";

cluster.disconnect(() => {
  console.log("all workers disconnected");
});

Try it

Node.js Disconnecting all workers

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.

Node.js Finish the current work, then leave

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

NODE
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") or process.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 to worker.kill().
  • exitedAfterDisconnect separates crashes from deliberate stops. In an 'exit' handler, only restart workers when it is false, otherwise a planned shutdown would trigger an endless restart loop.
  • In the worker, cluster.worker.disconnect() (or process.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, use server.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.