Introduction

If a Spring Boot service stops immediately while requests are still running, clients can see dropped connections, partial work, or corrupted workflows. The right solution is graceful shutdown: stop accepting new traffic, let in-flight requests finish, and only then complete the shutdown sequence.

Use Spring Boot’s Graceful Shutdown Support

Modern Spring Boot has built-in graceful shutdown support. Enable it with:

server.shutdown=graceful
spring.lifecycle.timeout-per-shutdown-phase=30s

or in YAML:

1server:
2  shutdown: graceful
3
4spring:
5  lifecycle:
6    timeout-per-shutdown-phase: 30s

With this enabled, the embedded server stops accepting new requests and waits for active ones to complete until the shutdown timeout is reached.

What Actually Happens During Shutdown

Graceful shutdown is not “keep the JVM alive forever”. It is a controlled sequence:

• the app receives a termination signal such as SIGTERM
• Spring begins its shutdown lifecycle
• the web server stops accepting new requests
• existing requests are allowed to finish within the timeout
• beans and resources are closed cleanly

That makes it much safer for rolling deployments, container restarts, and orchestrated shutdowns.

Test It with a Long Request

You can verify the behavior with a deliberately slow endpoint:

1import org.springframework.web.bind.annotation.GetMapping;
2import org.springframework.web.bind.annotation.RestController;
3
4@RestController
5public class SlowController {
6
7    @GetMapping("/slow")
8    public String slow() throws InterruptedException {
9        Thread.sleep(15000);
10        return "done";
11    }
12}

If graceful shutdown is enabled and the timeout is long enough, a request already inside /slow should still complete after the process receives the shutdown signal.

Containers and Load Balancers Matter Too

Application config alone is not enough if the runtime environment kills the process too quickly. For example:

• Kubernetes needs a termination grace period long enough for the app timeout
• load balancers should stop sending new requests before the pod or instance disappears
• process managers should send SIGTERM before SIGKILL

If the container runtime force-kills the app after a few seconds, Spring Boot never gets a real chance to finish the in-flight work.

Keep Request Handlers Interrupt-Safe

Graceful shutdown works best when request handlers do not block forever and when downstream calls have sensible timeouts. If a request hangs indefinitely on a remote dependency, shutdown can stall until the configured limit is reached.

That means you should still configure:

• HTTP client timeouts
• database timeouts
• thread-pool sizing

Graceful shutdown is not a substitute for well-bounded request execution.

Background Work Is a Separate Problem

The title often focuses on HTTP requests, but many Spring apps also have async jobs, schedulers, or message consumers. Those workloads need their own shutdown coordination. Letting web requests finish does not automatically guarantee background queues drain safely.

If you use custom executors, make sure they are managed beans and participate in shutdown rather than being ad hoc thread pools left running outside the container lifecycle. That distinction becomes very important in services that mix APIs with queue consumers or scheduled maintenance tasks.

Common Pitfalls

• Expecting graceful shutdown to work without setting server.shutdown=graceful.
• Configuring a long Spring timeout while the container or orchestrator kills the process much sooner.
• Forgetting that new traffic must be drained at the load balancer or platform level too.
• Allowing request handlers to block indefinitely on downstream systems.
• Assuming background jobs are covered automatically just because HTTP shutdown is graceful.

Summary

• Enable graceful shutdown with server.shutdown=graceful.
• Set a realistic spring.lifecycle.timeout-per-shutdown-phase for your request durations.
• Make sure the runtime environment gives Spring Boot enough time to finish in-flight work.
• Test shutdown behavior with slow endpoints instead of assuming the configuration is correct.
• Treat background task shutdown as a separate concern from request draining.