What is Node.js graceful shutdown and why does SIGTERM matter?

Graceful shutdown is an ordered sequence, not a single process.on('SIGTERM') callback. The process stops accepting new connections, lets in-flight requests finish, closes idle and keep-alive sockets, releases resources such as database pools and message consumers, flushes logs, and only then exits. Each step depends on the one before it. If you close the database pool before requests drain, the last requests fail on a dead connection.

SIGTERM is how the outside world asks your process to stop. Kubernetes sends it when it deletes a pod, docker stop sends it to the container's main process, and process managers such as systemd send it by default when stopping a service. The signal starts a grace period (30 seconds by default in Kubernetes, 10 in docker stop). When the grace period ends, the process receives SIGKILL, which cannot be caught or deferred. Anything still running at that point is cut off.

If you do not handle SIGTERM, Node's default behavior is to terminate immediately. In-flight requests are dropped, clients see connection resets, and buffered log lines and queue acknowledgements that have not been written yet are lost. A lost ack usually means the message is redelivered and processed twice.

You need this for any long-running service behind a load balancer or deployed with rolling updates. It is overkill for short-lived CLIs and for batch scripts that are safe to rerun.

The payoff is operational. Without graceful shutdown, every deploy produces a brief spike of 502s and resets. Someone eventually investigates that spike as an incident, and the time is wasted, because the cause is the deploy itself.

Who should use graceful shutdown?

Any team running a Node.js process that other systems depend on while it is running should implement it. In practice that means:

  • HTTP API and web servers built on Express, Fastify or plain http.Server, especially behind a load balancer or ingress that keeps connections alive.
  • Services deployed on Kubernetes, Docker or systemd, where the platform stops processes routinely and always starts with SIGTERM.
  • Queue and stream consumers that hold unacknowledged messages. A clean stop decides whether a message is acked once or redelivered.
  • Servers with long-lived connections such as WebSockets, server-sent events or streaming responses, which never go idle by themselves.
  • Platform and SRE engineers who own deployment pipelines and need rollouts that do not page anyone.

It matters less for short-lived CLIs, one-off scripts and batch jobs that can be rerun from the start. Even there, a SIGINT handler that removes temporary files or releases a lock can be useful.

When should graceful shutdown be used?

Add it before the service's first rolling deploy, not after the first deploy-time incident. The handler runs every time the platform stops a process, and that happens more often than most teams expect:

  • Rolling updates and redeploys. Each old pod or container receives SIGTERM as its replacement becomes ready.
  • Autoscaling down. Instances are removed while they are still serving traffic.
  • Node maintenance. Draining a Kubernetes node for upgrades or repairs evicts its pods with SIGTERM.
  • Preemptible or spot capacity. Reclaimed nodes stop their workloads on short notice.
  • Local development. Ctrl+C sends SIGINT, and the same shutdown path lets file watchers and test runners restart the server cleanly.

Some symptoms show the handler is missing or broken: a burst of 502s or connection resets that lines up with deploys, duplicate processing of queue messages after a rollout, truncated logs at the end of a pod's life, or pods that always take the full grace period to terminate.

Does your Node process actually receive SIGTERM in a container?

When shutdown misbehaves in a container, the cause is often that the process never saw the signal. In a container, whatever the image starts becomes PID 1, and two things go wrong there.

First, a shell-form CMD npm start is run through /bin/sh -c, so the shell may become PID 1 instead of Node. Many shells do not forward SIGTERM to their children. Package-manager script wrappers add another layer that may not reliably pass signals through. When Docker or Kubernetes sends SIGTERM, the wrapper receives it and Node does not. After the grace period, everything is killed with SIGKILL, and none of your cleanup code runs.

Second, the Linux kernel treats PID 1 specially. A signal with no installed handler is ignored instead of triggering its default action. Even when Node runs directly as PID 1, SIGTERM does nothing unless you register a handler.

The fix has two parts. First, use exec-form CMD ["node", "server.js"] so Node is the process that receives signals. Optionally, run a minimal init process such as tini, or use docker run --init, as PID 1. It forwards signals to Node and reaps zombie processes, which matters if your app spawns child processes.

Second, register handlers with process.on('SIGTERM', ...) and process.on('SIGINT', ...), both pointing to one shutdown function. Make that function idempotent with a guard flag. Orchestrators and impatient developers can send a second signal, and two overlapping shutdowns can close resources twice. Log when shutdown begins and when it finishes, so the logs show whether a pod exited cleanly or was killed partway through.

// Dockerfile: use exec form so node, not /bin/sh or npm, receives SIGTERM:
//   CMD ["node", "server.js"]
// Optional: run a minimal init as PID 1 to forward signals and reap zombies: docker run --init ...
const express = require('express');

const app = express();
app.get('/', (req, res) => res.send('ok'));
const server = app.listen(3000, () => console.log('listening on :3000'));

let shuttingDown = false;

function shutdown(signal) {
  // Idempotent: a second SIGTERM/SIGINT must not start an overlapping shutdown.
  if (shuttingDown) {
    console.log(`${signal} received, shutdown already in progress`);
    return;
  }
  shuttingDown = true;
  console.log(`${signal} received, shutdown starting`);

  // Safety net: exit on our own terms before the orchestrator sends SIGKILL.
  const timer = setTimeout(() => {
    console.error('shutdown timed out, forcing exit');
    process.exit(1);
  }, 10000);
  timer.unref(); // don't keep the event loop alive just for this timer

  // Stop accepting new connections; the callback runs once open ones have closed.
  server.close((err) => {
    if (err) {
      console.error('error during shutdown', err);
      process.exit(1);
    }
    console.log('shutdown complete');
    process.exit(0);
  });
}

// Explicit handlers are required: as PID 1, a signal with no handler is ignored.
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));

An Express server started with exec-form CMD that registers SIGTERM and SIGINT handlers pointing to one guarded, idempotent shutdown function that logs when shutdown starts and when it completes.

How does graceful shutdown work, step by step?

Order matters more than any individual step. Each stage depends on the one before it having finished, so the sequence runs from the outside of the process inward.

  1. Mark the instance not-ready. Flip a flag so the readiness endpoint starts returning 503. This tells the orchestrator and load balancer to stop routing new traffic here.
  2. Keep serving briefly. Endpoint removal propagates asynchronously, so requests can keep arriving for a few seconds after SIGTERM. Serve them normally during this delay.
  3. Stop accepting connections. Call server.close() in Express or fastify.close() in Fastify. The listening socket closes, and existing connections stay open.
  4. Drain in-flight requests. Let handlers that have already started run to completion.
  5. Close dependencies. Shut down database pools, stop queue consumers so they take no new messages, and clear intervals and timers.
  6. Exit naturally. When nothing holds the event loop open, Node exits on its own. If the process lingers, something is still open, and that is a bug to find. Calling process.exit() would hide it.

Timeline

Time Event
t = 0 SIGTERM arrives; readiness fails
0 → a few s Traffic still arrives; keep serving
then Listener closes; drain begins
drain done Pools, consumers and timers close
before grace period ends Process exits on its own
grace period ends (Kubernetes default: 30 s) SIGKILL, no cleanup

The ordering trap

A common mistake is to close the database pool at the same time as the HTTP server, or before it. server.close() returns right away, but handlers are still mid-flight. When those handlers try to acquire a connection, the pool is already gone. Each one throws, and the error handler converts it to a 500. A deploy meant to be invisible instead produces a burst of errors. The fix is to wait for the server's close callback, or the resolved close() promise, before closing anything those handlers depend on.

 t=0  SIGTERM arrives
   v
 +-----------------------------+
 | 1. Mark not-ready           |  readiness probe returns 503
 +-----------------------------+
   v
 +-----------------------------+
 | 2. Keep serving a few s     |  endpoint removal still propagating
 +-----------------------------+
   v
 +-----------------------------+
 | 3. Stop accepting           |  server.close() / fastify.close()
 +-----------------------------+
   v
 +-----------------------------+      +------------------------------+
 | 4. Drain in-flight requests |<-----| WRONG: pool closed with or   |
 +-----------------------------+      | before step 3 -> handlers    |
   v  only after drain is done        | cannot acquire conn -> 500s  |
 +-----------------------------+      +------------------------------+
 | 5. Close DB pools, queue    |
 |    consumers, timers        |
 +-----------------------------+
   v
 +-----------------------------+
 | 6. Event loop empty: exits  |  no process.exit() needed
 +-----------------------------+
   :
 grace period ends (k8s default 30 s) -> SIGKILL, no cleanup

The shutdown sequence runs from SIGTERM to a natural exit before the grace period ends. Closing the database pool before the drain completes makes in-flight handlers fail with 500s.

How do you drain keep-alive sockets when Express server.close() hangs?

Waiting for the close callback can take much longer than expected. server.close() stops the listener from accepting new connections, but its callback only fires once every existing connection has ended. HTTP/1.1 clients and load balancers keep sockets open after a response so they can reuse them. An idle keep-alive socket carries no request, yet it still counts as an open connection. If the client never sends another request, the socket stays open until the keep-alive timeout expires or the client hangs up, and your close callback waits for it.

The fix is to track connection state yourself. Listen for the server's connection event and add each socket to a set. Mark a socket busy when a request arrives on it, and mark it idle when the response emits finish. When shutdown begins, take three steps:

  • Destroy idle sockets immediately. No request is in progress on them, so a client that tries to reuse one sees a closed connection and opens a new one, ideally to another instance.
  • Add Connection: close to responses while draining. A small Express middleware can check a draining flag and set the header. Busy sockets then close cleanly after their current response instead of returning to the idle pool.
  • Prefer built-in methods where they exist. Recent Node versions add server.closeIdleConnections() and server.closeAllConnections() to http.Server. Check your runtime's documentation, and keep the manual tracking as a fallback.

Keep the two kinds of socket separate. Destroying an idle socket is safe. Destroying an active one resets a real request in progress, which recreates the error burst you are trying to avoid. Use closeAllConnections() or a blanket destroy only as a last resort, after the shutdown deadline has passed.

const express = require('express');

const app = express();
let draining = false;

// While draining, ask clients not to reuse the socket after this response.
app.use((req, res, next) => {
  if (draining) res.set('Connection', 'close');
  next();
});
app.get('/', (req, res) => res.send('ok'));

const server = app.listen(3000);
const sockets = new Map(); // socket -> number of in-flight requests

server.on('connection', (socket) => {
  sockets.set(socket, 0);
  socket.on('close', () => sockets.delete(socket));
});

server.on('request', (req, res) => {
  const s = req.socket;
  sockets.set(s, (sockets.get(s) || 0) + 1);
  res.on('finish', () => {
    const n = sockets.get(s) - 1;
    sockets.set(s, n);
    // A socket that just went idle during shutdown is closed gracefully.
    if (draining && n === 0) s.end();
  });
});

process.on('SIGTERM', () => {
  draining = true;
  server.close(() => process.exit(0)); // stop accepting; fires when all sockets end
  // Use the built-in method if this Node version has it; manual tracking is the fallback.
  if (typeof server.closeIdleConnections === 'function') server.closeIdleConnections();
  for (const [s, n] of sockets) if (n === 0) s.destroy(); // idle only: safe
  // Last resort after the deadline: this resets requests still in progress.
  setTimeout(() => { for (const s of sockets.keys()) s.destroy(); process.exit(1); }, 10000).unref();
});

An Express server that tracks in-flight requests per socket, destroys only idle sockets on SIGTERM, sends Connection: close while draining, and force-closes active sockets only after a 10-second deadline.

How does fastify close() handle shutdown and plugin teardown?

Fastify takes on more of the shutdown work than Express does. Calling fastify.close() stops the listener from accepting new connections and then runs every onClose hook. Hooks run in reverse registration order, so a plugin registered last is torn down first. This ordering matters because plugins usually depend on what was registered before them. A cache plugin built on a Redis client should close before the client does, and a route plugin that writes to Postgres should finish before the pool shuts down. If each plugin registers its own onClose hook that ends its client, the framework handles dependency order and the signal handler stays small.

The handler should listen for SIGTERM once, await fastify.close(), and exit with a non-zero code if any hook throws. Keep the hard-deadline timer from the previous section in place, because a hook that never resolves will block close() indefinitely.

close() does not remove the keep-alive problem. Idle sockets can still keep the server open. Fastify has a server option for force-closing connections during close (forceCloseConnections), but its availability and default behavior depend on your Fastify and Node versions. Check the documentation for the version you run instead of assuming idle sockets are handled.

Responsibility Express Fastify
Stop accepting connections server.close() on the http.Server fastify.close()
Tear down DB clients and plugins Manual, in the order you write it onClose hooks, reverse registration order
Idle keep-alive sockets Manual tracking or closeIdleConnections() Server option; check your version
Hard deadline Your timer Your timer
import Fastify from 'fastify';
import pg from 'pg';

const app = Fastify({ logger: true });
const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });

// Registered first, so it runs last. The pool must outlive everything that uses it.
app.addHook('onClose', async () => {
  await pool.end();
  app.log.info('pg pool closed');
});

// Registered later, so it runs first. It can still use the pool.
app.addHook('onClose', async () => {
  await pool.query('UPDATE workers SET status = $1 WHERE id = $2', ['stopped', 'worker-1']);
  app.log.info('worker marked stopped');
});

app.get('/health', async () => ({ ok: true }));

process.once('SIGTERM', async () => {
  // Hard deadline: a hook that never resolves would otherwise block close() forever.
  const timer = setTimeout(() => {
    app.log.error('shutdown deadline exceeded');
    process.exit(1);
  }, 10_000);
  timer.unref();

  try {
    await app.close(); // stops accepting connections, then runs onClose hooks
    process.exit(0);
  } catch (err) {
    app.log.error(err, 'onClose hook failed');
    process.exit(1);
  }
});

await app.listen({ port: 3000, host: '0.0.0.0' });

A SIGTERM handler that awaits fastify.close() under a hard deadline, with onClose hooks registered so the Postgres pool is closed last because it was registered first.

How do you handle timeouts, the Kubernetes endpoint race, and long-lived connections?

Start a hard deadline the moment shutdown begins. When it fires, log what is still open and call process.exit(1). The non-zero code shows that the drain failed instead of hiding it. Call unref() on the timer so the timer alone does not keep a cleanly drained process alive. The deadline must expire before Kubernetes sends SIGKILL. Otherwise you never get the log line.

Kubernetes removes the pod from endpoints in parallel with sending SIGTERM, not before it. Kube-proxy and ingress controllers can keep routing to the pod for a short window. To cover that window, fail readiness immediately and wait before closing the listener. Use either a preStop sleep or an in-process delay. A preStop hook runs before SIGTERM and counts against terminationGracePeriodSeconds.

Illustrative estimate (assumed numbers, not a benchmark): hardTimer = grace − preStop − margin. With grace = 30 s, preStop = 5 s and margin = 3 s, the hard timer is 22 s, measured from SIGTERM.

Long-lived connections never go idle, so you have to close them yourself:

  • WebSockets: send close code 1001 ("going away") and let clients reconnect elsewhere.
  • SSE: emit a final event, then call res.end().
  • Streaming responses: finish the current chunk, or abort so the client can retry.
Choice Risk
Long drain window Slower deploys; old and new pods both hold capacity during rollouts
Short drain window Degrades into a hard kill with dropped requests
Early process.exit() Pending log, metric and stdout writes are lost
Never exiting One leaked handle hangs the pod until SIGKILL

When is graceful shutdown not enough, and what are the alternatives?

A shutdown handler only runs if the process gets to run it. SIGKILL after the grace period, an out-of-memory kill, an uncaught exception or a lost node all end the process without warning. Any job or queue message in flight at that moment is abandoned. The defence is to make consumers idempotent and to acknowledge messages only after the work commits, so a redelivery repeats the work safely instead of corrupting state.

Clean drains also cannot remove every client-side error. If a client reuses a pooled keep-alive socket at the same moment the server closes it, the request fails with a reset even though the server behaved correctly. Clients should retry idempotent requests (GET, PUT, or POST with an idempotency key) once on a connection reset.

Approach What it covers What it misses
Hard kill plus retries Simple; correctness rests on idempotency Every deploy produces errors and retry load
preStop sleep only Gives the endpoint removal time to propagate Never closes idle sockets or finishes long requests
Process manager or proxy draining Stops new traffic before the app knows Has no view of in-process work or resource cleanup
Full in-process handling Drains sockets, flushes writes, closes pools Takes code and tests, and still needs retries for crashes

The in-process approach costs a few dozen lines plus a test that sends SIGTERM under load. Compare that with the time spent tracing a spike of 502s that appears on every rollout. Combine it with idempotent consumers and client retries. No single layer covers every way a process can stop.

How can graceful shutdown save engineering time?

The time savings come from removing a recurring class of problems that are expensive to diagnose because they look like real failures:

  • Fewer false incidents. Deploy-time 502s, resets and error-rate alerts disappear, so on-call engineers stop investigating errors that the rollout itself caused.
  • Less data cleanup. Consumers that stop taking messages and ack only completed work avoid duplicate processing after deploys. Nobody has to reconcile double-sent emails or double-applied updates by hand.
  • Faster debugging when shutdown does go wrong. Start and finish log lines, a non-zero exit code on timeout, and a dump of process.getActiveResourcesInfo() point straight to the leaked handle. Without them, the only symptom is a pod that is SIGKILLed with no trace.
  • Safer, more frequent deploys. When a rollout is invisible to users, teams can ship during working hours and in smaller batches instead of grouping changes into scheduled maintenance windows.
  • Shared code across services. One tested shutdown module, or a set of Fastify onClose hooks per plugin, can be reused by every service instead of each team rediscovering the same bugs.

The work is front-loaded and small: a handler, a readiness flag, a deadline timer and a load test. The cost of skipping it recurs on every deploy, scale-down and node drain.

How can you verify graceful shutdown locally?

Start the service directly with node, not through npm start. A package-manager wrapper can swallow or delay the signal, so the test would measure the wrapper instead of your shutdown handler. Point a load generator such as autocannon or wrk at an endpoint with keep-alive enabled, so connections are reused the way a real load balancer reuses them. A slow endpoint that takes a second or two to respond works best, because it guarantees that requests are in flight when the signal arrives. While load is running, send kill -TERM <pid>.

The load generator's summary should show zero socket errors and zero non-2xx responses for requests that were accepted before shutdown began. Connection-refused errors after the listener closes are expected locally, because no load balancer is rerouting traffic. Only resets on established connections indicate a real bug.

Next, check how the process ended. Record the time between the signal and exit, and confirm it stays under your forced-exit timeout. Then inspect the exit code. A code of 0 means your handler finished cleanly. A code of 143 (128 + 15) means the default SIGTERM behaviour killed the process, which usually means your handler was never registered.

If the process never exits, something is still holding the event loop open. Log process.getActiveResourcesInfo() shortly before your timeout fires. A lingering TCPSocketWrap usually points to a keep-alive socket or a database pool. A Timeout usually points to an interval that was never cleared.

Reusable checklist

  • Run under sustained keep-alive load with slow requests in flight.
  • Send SIGTERM and confirm no resets on accepted requests.
  • Confirm exit code 0.
  • Confirm the process exits within the timeout.
  • Confirm no active handles remain at exit.
  • Repeat the test inside the container image to catch PID 1 signal problems.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to node.js graceful shutdown sigterm, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.