Mastering Graceful Shutdown in Spring Boot 2.3: A Complete Guide

When a Spring Boot application receives a request that executes business logic, a forced termination (e.g., kill) will close the embedded container (Tomcat, Jetty, etc.) immediately, causing the request to fail and potentially leading to data inconsistency because transactions are not rolled back.

Graceful Shutdown

Since Spring Boot 2.3, graceful shutdown is built in and works with embedded web servers such as Jetty, Reactor Netty, Tomcat, and Undertow, for both reactive and servlet‑based applications.

How to enable

Set the property server.shutdown=graceful. When the web container shuts down, it stops accepting new requests and waits for active requests to finish within a configurable buffer period.

Configuration experience

Buffer period timeout-per-shutdown-phase configuration

The default timeout is 30 seconds; if active requests do not finish within this period, the server shuts down regardless of their state, so the timeout should be set appropriately.

Graceful shutdown workflow

Send a request to the service.

Issue the shutdown command.

The server receives the shutdown signal and stops accepting new requests.

Active requests complete, then the server terminates.

Related knowledge

Use kill -2 (equivalent to Ctrl+C) to trigger Java's ShutdownHook for graceful shutdown, instead of kill -9, which forcefully terminates the process without invoking the hook.

@Override
public void registerShutdownHook() {
    if (this.shutdownHook == null) {
        this.shutdownHook = new Thread(SHUTDOWN_HOOK_THREAD_NAME) {
            @Override
            public void run() {
                synchronized (startupShutdownMonitor) {
                    doClose();
                }
            }
        };
        Runtime.getRuntime().addShutdownHook(this.shutdownHook);
    }
}

Graceful shutdown via Actuator

Send a POST request to /actuator/shutdown to trigger graceful shutdown programmatically.

Shutdown endpoint source code

@Endpoint(id = "shutdown", enableByDefault = false)
public class ShutdownEndpoint implements ApplicationContextAware {
    @WriteOperation
    public Map<String, String> shutdown() {
        Thread thread = new Thread(this::performShutdown);
        thread.setContextClassLoader(getClass().getClassLoader());
        thread.start();
        return Collections.singletonMap("status", "shutdown initiated");
    }
    private void performShutdown() {
        try {
            Thread.sleep(500L);
        } catch (InterruptedException ex) {
            Thread.currentThread().interrupt();
        }
        this.context.close();
    }
}

Different web container graceful shutdown behaviors

Tomcat 9.0.33+ : Stops accepting new requests; existing requests wait until timeout.

Reactor Netty : Stops accepting new requests; clients wait for timeout.

Undertow : Stops accepting new requests; new requests receive HTTP 503 immediately.

By configuring server.shutdown=graceful and adjusting timeout-per-shutdown-phase, Spring Boot applications can ensure ongoing requests finish gracefully, avoiding data loss and inconsistent states during shutdown.