Skip to content
Tutorials Center
My learning

Topics

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.

NODE
process.once('SIGTERM', () => shutdown('SIGTERM'));
process.once('SIGINT', () => shutdown('SIGINT'));

Try it

Node.js A shutdown function for an HTTP server

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 Cleanup steps in order with a failure guard

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

  1. Mark the process as shutting down. Make health checks fail so a load balancer stops sending traffic, and ignore a second signal.
  2. Stop accepting connections. server.close() stops listening and calls its callback once every connection has ended. It does not end connections itself.
  3. Wait for in-flight work. Requests being handled, queue jobs, and writes in progress should finish.
  4. 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 hold close() open until their keep-alive timer expires.
  5. 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).
  6. Close resources in reverse order: servers first, then queues, then database pools, then loggers.
  7. Exit. Set process.exitCode and let the event loop drain; call process.exit() only after the deadline.

Usage notes

  • Use once, not on, for signal handlers, so a second Ctrl+C can 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. SIGINT works 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.