Spring Boot graceful shutdown: finish accepted requests within a deadline

Budget the whole stop sequence

A receipt POST may be inside validation, a database transaction or an external call when termination begins. Set a shutdown-phase deadline that is longer than the expected in-flight request but shorter than the platform termination allowance. A 20-second Spring phase inside a 10-second container kill window cannot complete as intended.

The embedded server's graceful stop is part of application-context close. New requests may be rejected at the network layer, and persistent connections complicate what a client observes. A client that loses the response after a committed write needs an idempotency contract before retrying. Shutdown does not roll back every action already committed.

Prove the signal path

Run the packaged application as a child process, hold one bounded request open, send the platform's normal termination signal, and record whether the response finishes. Then try a new request. Repeat with the real ingress or proxy, because a direct loopback test misses connection draining in front of the process.

The current kit tests live health and authentication over loopback, not a shutdown signal. The readiness fixture shows a dependency outage; it does not prove termination behavior. The configured phase deadline is a policy until the deployed process test runs.

Working sketch

spring.lifecycle.timeout-per-shutdown-phase=20s
# Platform termination allowance must exceed this phase and its other stop work.

Verification boundary

No graceful-stop process test exists in the source kit. ReadinessHealthGroupHttpTest covers a different live HTTP boundary.

Costs and limits

The property is a release setting, not evidence that a proxy drains connections or that a committed POST response reaches the client.

Common Mistakes

• Do not set the platform kill deadline shorter than the application stop budget.
• Do not assume a lost response means a database transaction rolled back.
• Do not infer server shutdown behavior from a direct context-close unit test.

Read next

Spring Boot readiness health group: withdraw traffic on a required dependency failure, Spring POST idempotency keys: replay the same receipt result, Spring Boot receipt API project: build, test and inspect the limits, Spring TaskScheduler shutdown: stop new polls and account for in-flight work.