What is a Node.js graceful shutdown and why does server.close() fall short?

A graceful shutdown is a time-boxed sequence, not a single call. When the process is told to stop, it stops accepting new work, lets in-flight HTTP requests and queue jobs finish, closes dependencies in the reverse order they were opened (consumers first, then caches and database pools), and exits on its own before the platform's deadline.

This matters because deploys and scale-downs kill healthy processes all the time. Any service behind a load balancer or orchestrator, and any worker consuming a queue, gets terminated routinely. The usual lifecycle works like this:

  1. The orchestrator sends SIGTERM.
  2. A grace period runs.
  3. If the process is still alive when the grace period ends, the orchestrator sends SIGKILL, which cannot be caught.

Everything useful has to happen inside that window. Without a handler, Node's default response to SIGTERM is to exit immediately. Requests mid-flight get reset, and jobs are abandoned partway through.

server.close() looks like the fix, but it only stops the listener from accepting new connections. It then waits for existing connections to end. With HTTP keep-alive, clients and load balancers hold idle sockets open between requests, and those sockets can keep the process alive until SIGKILL arrives. How close() treats idle connections has changed across Node releases, so handle them explicitly rather than relying on the default.

Know the limits up front. None of this protects you from SIGKILL, out-of-memory kills, node failures, or crashes. Graceful shutdown reduces errors during routine termination. You still need at-least-once delivery, idempotent job handlers, and client retries.

  Orchestrator                      Node.js process
 +----------------+  1. SIGTERM    +-----------------------------------+
 | deploy or      |--------------->| a. stop accepting new work        |
 | scale-down     |                |    server.close(), pause consumers|
 +----------------+                | b. drain in-flight HTTP + jobs    |
         |                         |    destroy idle keep-alive sockets|
         | 2. grace period         | c. close deps in reverse order    |
         |    timer runs           |    consumers -> cache -> DB pool  |
         |                         | d. exit on its own before deadline|
         v                         |                                   |
 +----------------+                +-----------------------------------+
 | deadline hit   |                          |                   |
 +----------------+                          | in time           | stuck
         |                                   v                   v
         | 3. SIGKILL                 +---------------+   +------------------+
         | (uncatchable)              | clean exit    |   | killed mid-work  |
         |                            | before kill   |   | requests reset,  |
         |                            +---------------+   | jobs abandoned   |
         +----------------------------------------------->| needs redelivery |
                                                          +------------------+

 stuck: e.g. server.close() alone, idle keep-alive sockets hold it open
 Not covered: SIGKILL, OOM kills, node failures, crashes. Keep
 at-least-once delivery, idempotent job handlers and client retries.

After SIGTERM, the process must stop intake, drain HTTP requests and jobs, and close dependencies in reverse order before the grace period ends. Otherwise SIGKILL ends it mid-work, which can happen when idle keep-alive sockets keep it alive after server.close().

Why doesn't my Node.js container receive SIGTERM?

When Kubernetes or a container runtime stops a container, it sends SIGTERM to PID 1 in the container's PID namespace, waits for the grace period, and then sends SIGKILL. Your handler only runs if node receives that first signal. Three common setups prevent that.

Shell-form entrypoints. Writing CMD node server.js as a plain string makes the runtime wrap it in /bin/sh -c. The shell becomes PID 1 and node becomes its child. A shell running a command does not forward SIGTERM to that child. Some shells replace themselves with a single simple command, but you should not rely on that. The usual outcome is that the container ignores SIGTERM until the grace period expires and SIGKILL arrives. That shows up as slow deploys and dropped requests.

npm as the parent. CMD ["npm", "start"] puts npm at PID 1. npm then runs your script through a shell, which adds another process between the signal and node. Signal forwarding through that chain has varied over time, so treat it as unreliable.

PID 1 semantics. The kernel does not apply default signal actions to PID 1. A signal with no installed handler is ignored. If node is PID 1 without a SIGTERM handler, nothing happens. PID 1 is also responsible for reaping orphaned zombie processes, and node does not do that.

The fix is to use exec-form CMD ["node", "server.js"] so node is PID 1 with your handler installed. If your app spawns child processes, run a minimal init such as tini as PID 1 instead. It forwards signals and reaps zombies.

To confirm which process is PID 1, run cat /proc/1/cmdline or ps inside the running container.

FROM node:20-alpine

# tini is a minimal init: as PID 1 it forwards signals to its child
# and reaps orphaned zombie processes.
# On Alpine the package installs the binary at /sbin/tini.
RUN apk add --no-cache tini

WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .

USER node

# Avoid both of these. Each puts another process between the runtime's
# SIGTERM and node:
#   CMD node server.js       # shell form, so /bin/sh -c is PID 1
#   CMD ["npm", "start"]     # npm is PID 1 and runs the script via a shell

# Exec form, JSON array, no shell. tini is PID 1 and node is its direct
# child, so SIGTERM reaches the process.on('SIGTERM') handler in node.
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["node", "server.js"]

# If you do not spawn child processes, you can drop tini and keep only
#   CMD ["node", "server.js"]
# node is then PID 1. Without a SIGTERM handler, node ignores the signal.
#
# With plain `docker run`, the --init flag injects a similar init process
# and you do not need to install tini.
#
# To confirm which process is PID 1 in a running container:
#   docker exec <container> sh -c 'tr "\0" " " < /proc/1/cmdline; echo'
#   docker exec <container> ps -o pid,ppid,args
# Expected output: PID 1 is '/sbin/tini -- node server.js',
# and node is a child process with PPID 1.

A Dockerfile that uses exec-form ENTRYPOINT and CMD with tini as PID 1, so SIGTERM reaches node directly. Comments show the shell-form and npm patterns to avoid and how to check which process is PID 1.

How do you write a SIGTERM handler that runs only once?

Put all shutdown logic in one function, shutdown(signal), and make it the only code that decides when the process exits. Register it for both SIGTERM (sent by orchestrators) and SIGINT (Ctrl+C locally) so both paths are exercised the same way. Guard it with a module-level shuttingDown flag. If the flag is already set, log the repeated signal and return. Without the guard, a second signal (an impatient operator, or a supervisor that resends) starts a second drain that races the first and closes resources out from under it.

On the first call, start a hard deadline timer that logs a timeout and calls process.exit(1). Call unref() on it so the timer alone does not keep the event loop alive after everything else has closed. Log each phase (signal received, readiness failed, HTTP closed, workers drained, dependencies closed) with an ISO timestamp and elapsed milliseconds. When a shutdown stalls in production, those logs show which phase ate the budget.

Trade-offs to decide deliberately:

  • Competing handlers. Frameworks, APM agents and some libraries register their own signal listeners. Some exit immediately and skip your cleanup. Others trigger a second shutdown. Inspect process.listeners('SIGTERM') at startup and disable or remove any listener you don't own.
  • Timeout exit code. A non-zero exit on timeout surfaces stuck drains, but it may also count as a crash for restart policies and alerting. Pick one behavior and document it.
  • Explicit exit vs. natural drain. process.exit() is deterministic but can drop asynchronous log writes still buffered for piped stdout. Setting process.exitCode and letting the loop empty preserves output, but it hangs if any handle leaks. The unref'd deadline timer is your backstop for that case.
const http = require('node:http');

const SHUTDOWN_TIMEOUT_MS = 25000; // keep below the orchestrator's grace period
const server = http.createServer((req, res) => res.end('ok')).listen(3000);
let shuttingDown = false;
let ready = true; // read by a readiness endpoint (not shown)
let shutdownStart = 0;

const log = (phase) =>
  console.log(`${new Date().toISOString()} shutdown phase=${phase} elapsedMs=${Date.now() - shutdownStart}`);

async function drainWorkers() { /* stop pulling jobs, await in-flight ones */ }
async function closeDependencies() { /* close DB pools, queue connections */ }

async function shutdown(signal) {
  if (shuttingDown) return log(`repeat-signal-ignored ${signal}`); // guard against re-entry
  shuttingDown = true;
  shutdownStart = Date.now();
  log(`signal-received ${signal}`);

  // Backstop for a hung phase or leaked handle. unref() so this timer alone
  // never keeps the process alive once everything else has closed.
  setTimeout(() => { log('deadline-exceeded'); process.exit(1); }, SHUTDOWN_TIMEOUT_MS).unref();

  try {
    ready = false; log('readiness-failed');
    const closed = new Promise((ok, fail) => server.close((err) => (err ? fail(err) : ok())));
    server.closeIdleConnections(); // don't wait on idle keep-alive sockets
    await closed; log('http-closed');
    await drainWorkers(); log('workers-drained');
    await closeDependencies(); log('dependencies-closed');
    process.exitCode = 0;
  } catch (err) {
    log(`error ${err.message}`);
    process.exitCode = 1;
  }
  // No process.exit() here: let the loop empty so buffered log writes flush.
}

process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);
console.log(`SIGTERM listeners at startup: ${process.listenerCount('SIGTERM')}`); // expect 1

A single, re-entry-guarded shutdown owner for SIGTERM and SIGINT that logs each phase with timestamps, uses an unref'd deadline timer as a failing-exit backstop, and otherwise sets process.exitCode so the event loop can drain naturally.

Failing readiness and draining HTTP keep-alive connections

Start the drain at the routing layer, not the socket layer. When SIGTERM arrives, flip the readiness endpoint to return 503 and keep serving normally for a configurable delay, typically a few seconds longer than your probe interval multiplied by the failure threshold. Endpoint removal propagates asynchronously, so load balancers and node proxies may still send new connections to the pod during that window. If you close the listener immediately, those connections get refused. The client sees an error even though the pod was healthy a moment earlier.

After the delay, call server.close(). It stops accepting new connections and invokes its callback once every existing connection has ended. It does not end those connections itself. An idle keep-alive socket can hold the server open until its keep-alive timeout expires.

Approach What it does Limitation
closeIdleConnections() Closes sockets with no request in flight Only available on runtimes that support it; does nothing for busy sockets
Track sockets via 'connection' Keeps a set of sockets you can end or destroy You maintain the bookkeeping and handle 'close' cleanup
Connection: close header Tells clients to drop the socket after the current response Only affects sockets that receive another response

Long-lived connections need their own path. For WebSockets, send a close frame. For SSE and streaming responses, send a reconnect hint and end the stream. Allow a bounded window for clients to disconnect, then destroy whatever sockets remain.

Destroying a socket can race with a request that arrived on it a moment earlier. That request is cut off without a response. Configure clients and proxies to retry idempotent requests on connection reset so this race does not surface as an error.

const http = require('node:http');

const DRAIN_DELAY_MS = Number(process.env.DRAIN_DELAY_MS ?? 15000); // > probe period * failureThreshold
const FORCE_CLOSE_MS = 10000; // bounded window for remaining sockets
let shuttingDown = false;
const sockets = new Set();

const server = http.createServer((req, res) => {
  if (req.url === '/readyz') {
    res.statusCode = shuttingDown ? 503 : 200; // fail readiness, keep serving traffic
    return res.end();
  }
  // Once draining, tell keep-alive clients to drop the socket after this response.
  if (shuttingDown) res.setHeader('Connection', 'close');
  res.end('ok');
});

// Manual tracking so stragglers can be destroyed later.
server.on('connection', (socket) => {
  sockets.add(socket);
  socket.on('close', () => sockets.delete(socket));
});

process.once('SIGTERM', () => {
  shuttingDown = true; // step 1: routing layer stops sending new connections
  setTimeout(() => {
    // step 2: stop accepting; callback fires only after every socket has ended
    server.close(() => process.exit(0));
    server.closeIdleConnections?.(); // close keep-alive sockets with no request in flight
    // step 3: send WebSocket close frames / SSE reconnect hints to long-lived clients here
    setTimeout(() => {
      // step 4: force-close what is left; may cut off a request that just arrived
      for (const s of sockets) s.destroy();
    }, FORCE_CLOSE_MS).unref();
  }, DRAIN_DELAY_MS);
});

server.listen(8080);

A minimal Node.js HTTP drain sequence: fail readiness and wait, then call server.close(). Idle keep-alive sockets are closed and busy ones get Connection: close. Any sockets still open after a bounded window are destroyed.

How do you drain queue workers without losing jobs?

Queue workers need the same ordering as HTTP servers. First stop taking new work, then finish the work you already have. In practice, "stop" means pausing the consumer, breaking out of the polling loop, or cancelling the subscription. The order matters because a worker that keeps pulling messages while it drains will never reach zero in-flight jobs.

Track in-flight work with a counter or, better, a Set of job promises. Remove each promise when it settles. During shutdown, await Promise.allSettled([...inFlight]) gives you a single point to wait on.

Acknowledge a message only after its handler completes. Anything unacknowledged when the process exits, or still held under an expired lease, becomes visible again and goes to another worker. That makes redelivery your safety net, and it only works if jobs tolerate running twice:

  • Idempotent handlers. Use a dedupe key checked before side effects, or upserts instead of inserts.
  • Lease or visibility timeouts longer than typical job duration. Otherwise a slow job is redelivered while it is still running.
  • An AbortSignal passed into long jobs. The job can then checkpoint progress or stop cleanly between steps.

Long jobs force a choice:

Strategy Benefit Cost
Wait them out No job code changes May exceed any reasonable grace period and get killed anyway
Cooperative cancellation Bounded shutdown, partial progress saved Job code must check the signal and checkpoint correctly
Rely on redelivery Simplest shutdown path Requires idempotency; risks duplicate side effects such as emails or charges

How should you close dependencies and budget shutdown time?

Tear down in the reverse order of startup. Stop the HTTP server and queue consumers first, because they create new work. Then flush telemetry and logs while the process can still report what happened during the drain. Close database pools, caches, and broker connections last, since in-flight handlers may still need them until the final response or acknowledgement.

Within each phase, run independent closes through Promise.allSettled, and race each one against its own timeout. With Promise.all, one rejection short-circuits the result and you lose the outcome of the other steps. Without per-step timeouts, a single hung Redis client can consume the entire budget. With both, every dependency gets a bounded chance, every failure gets logged, and the process exits on time.

The internal deadline has to finish before the orchestrator sends SIGKILL:

internal deadline = grace period − readiness delay − safety margin

Illustrative estimate (assumed numbers, not a benchmark): Assume a 30 s grace period, a 5 s readiness delay, and a 3 s margin. That leaves a 22 s internal deadline. You could split it as 15 s for the HTTP and worker drain, 3 s for the telemetry flush, and 4 s for closing pools and brokers.

The drain window is a trade-off. A longer window interrupts fewer requests and jobs, but it slows every rollout and scale-down. The readiness delay is mostly a guess about how long your load balancer takes to stop routing to the instance. It adds that latency to every shutdown, including the ones where no traffic was in flight.

How do you test graceful shutdown, and when is it worth the effort?

Start with a local test that reproduces a real deploy. Run the service, point a load generator at it with keep-alive enabled and a fixed number of connections, and enqueue a job that sleeps long enough to still be running when the signal arrives. Then send kill -TERM to the Node.js process itself, not to a wrapper shell, so you exercise the same path the orchestrator uses.

Check three things. The load generator should report zero errors and zero connection resets. The job should either finish and be acknowledged, or be returned to the queue and picked up again exactly once. Total exit time should stay under your termination deadline. Use the phase timestamps from your shutdown logs to compute that last figure, measuring from signal received through readiness failed, server closed, and workers drained to process exit. This shows which phase used up the budget, which a single total cannot. Run the test in CI so a new dependency that holds the event loop open fails the build.

Most of the cost is the initial setup and the extra checkpoints it adds to job code. What you get back is time not spent chasing errors that only appear during deploys, or cleaning up after duplicate jobs. Keep it minimal for short-lived batch processes, for stateless work that is always retried, and on platforms that already drain traffic for you. The alternatives are to rely on at-least-once redelivery and client retries alone, or to use framework or library shutdown helpers. If you use helpers, make sure one place still owns the order in which things shut down.

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, 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.