How to Use a JVM Shutdown Hook to Drain In-Flight Requests

“How do you use a JVM shutdown hook to drain in-flight requests before exit?”

A shutdown hook is a Thread registered via Runtime.getRuntime().addShutdownHook(hook) that the JVM starts the moment it begins an orderly shutdown — normal main() return, System.exit(), or a signal like SIGTERM (Ctrl+C, kill, a Kubernetes pod being terminated). It never runs on SIGKILL/kill -9 or a native crash — there's no orderly shutdown sequence for those to hook into.

Runs on

SIGTERM, System.exit(), normal exit

Does NOT run on

kill -9 / SIGKILL, native crash

Typical use

stop new work → drain in-flight → close resources

Kubernetes sends SIGTERM, then waits terminationGracePeriodSeconds (default 30s) before escalating to SIGKILL. A shutdown hook that takes longer than that window to drain gets killed mid-drain regardless of how correct its logic is — the grace period is a hard budget, not a suggestion.

Runtime.getRuntime().addShutdownHook(new Thread(() -> {
    log.info("SIGTERM received, draining...");
    server.stopAcceptingNewConnections();
    boolean drained = server.awaitInFlightRequests(Duration.ofSeconds(25));
    if (!drained) log.warn("Forced shutdown with requests still in flight");
    connectionPool.close();
}, "shutdown-hook"));

Key takeaway: the hook's job is sequencing, not magic — stop the front door first so the in-flight count can only shrink, then wait for it to hit zero (bounded), then release resources. Skip the 'stop accepting new work' step and the hook can chase a moving target until the grace period runs out.

An uncaught exception inside a shutdown hook doesn't abort the shutdown sequence — the JVM runs every registered hook as its own thread, so one hook throwing just triggers its default UncaughtExceptionHandler (typically a stack trace on stderr) while the other registered hooks still run independently. That's easy to misread as "the hook must have failed silently and everything's fine" — in practice it means the specific cleanup step that threw never completed (a connection pool that didn't close, a flush that didn't happen), so a shutdown hook's own body should be wrapped in try/catch with explicit logging rather than left to rely on the default handler.

Every rolling deployment on Kubernetes or ECS depends on exactly this: a pod gets SIGTERM before it's removed from the load balancer's rotation and terminated, and a well-written shutdown hook is the difference between a clean deploy and a burst of connection-reset errors on every release.

Keywords they're listening for:

• ✓ addShutdownHook runs on SIGTERM/normal exit, not SIGKILL
• ✓ stop accepting new work before draining old work
• ✓ drain wait must be bounded by a timeout
• ✓ orchestrator grace period must exceed worst-case drain time

• ✗Assuming the shutdown hook always runs (it doesn't on SIGKILL or a crash)
• ✗No timeout on the drain wait, so the hook can block indefinitely on one stuck request
• ✗terminationGracePeriodSeconds shorter than the realistic worst-case drain time
• ✗Draining before stopping new connections, so the in-flight count never actually reaches zero

• ✓Stop accepting new connections first, then drain existing ones
• ✓Bound the drain wait with a timeout comfortably under the orchestrator's grace period
• ✓Log (and alert on) forced/incomplete shutdowns for visibility

1. 1What signal does Kubernetes send before force-killing a pod?
2. 2Why doesn't a shutdown hook run on kill -9?
3. 3How do you make an HTTP server stop accepting new connections but finish existing ones?
4. 4What happens if the shutdown hook itself throws an exception?

• Runtime.addShutdownHook
• SIGTERM
• Kubernetes terminationGracePeriodSeconds
• connection draining