Node.js Reference ยท Concepts and Pitfalls
Graceful shutdown in Node.js
How to stop a Node.js server cleanly: handle SIGTERM and SIGINT, stop accepting connections, finish in-flight requests, close resources, and force exit on a timeout.
A graceful shutdown lets a process finish what it is doing before it exits. Deployments, autoscalers and Ctrl+C all end processes by sending a signal: SIGTERM for "please stop" and SIGINT for an interactive interrupt. If your program ignores the signal, the platform waits a grace period and then kills it with SIGKILL, dropping in-flight requests, half-written files and open database transactions.
A good shutdown routine follows a fixed order: stop taking new work, wait for current work, release resources, then exit. A timer guards the whole thing so a stuck connection cannot hold the process hostage forever.
process.once('SIGTERM', () => shutdown('SIGTERM')); process.once('SIGINT', () => shutdown('SIGINT'));
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.
The shutdown sequence
- Mark the process as shutting down. Make health checks fail so a load balancer stops sending traffic, and ignore a second signal.
- Stop accepting connections.
server.close()stops listening and calls its callback once every connection has ended. It does not end connections itself. - Wait for in-flight work. Requests being handled, queue jobs, and writes in progress should finish.
- Deal with idle keep-alive sockets.
server.closeIdleConnections()closes connections that have no request in progress. Call it after the work is done: a socket that just served a response becomes idle only then, and idle sockets would otherwise holdclose()open until their keep-alive timer expires. - Force after a deadline.
server.closeAllConnections()cuts every remaining connection. Pick a deadline shorter than your platform's kill timeout (Kubernetes defaults to 30 seconds). - Close resources in reverse order: servers first, then queues, then database pools, then loggers.
- Exit. Set
process.exitCodeand let the event loop drain; callprocess.exit()only after the deadline.
Usage notes
- Use
once, noton, for signal handlers, so a secondCtrl+Ccan still kill a stuck process. - A signal handler replaces the default. Once you listen for
SIGTERM, Node no longer exits by itself; your handler is responsible for ending the process. - Windows does not deliver
SIGTERM.SIGINTworks from the console; see Cross-platform pitfalls. unref()the deadline timer so it never keeps the process alive on its own.server.close()takes a callback or emits'close'. The promise-less API is easy to forget to await.- Close WebSocket and SSE connections explicitly; they are long-lived and
close()waits for them forever. - Do not start new work in the handler. Queue consumers should stop pulling jobs before they finish the current one.
- Uncaught exceptions need the same path: log, run the shutdown, exit non-zero. See Unhandled errors.