Shutdown
When the application closes, the server stops. server.shutdown=graceful (the default) lets the requests in progress finish first. server.shutdown=immediate cuts them.
Why
A deployment, a restart or a scale-down stops the process while clients are being served. If the server closes at once, those clients get a broken connection: an order may be half saved, an upload lost. A graceful shutdown stops taking new connections, waits for the running requests, and only then closes. The load balancer sends new requests to the other instances in the meantime.
Use immediate when nothing is worth waiting for: in tests, in a tool, in development.
Example
# lib/resources/application.yml
server:
shutdown: graceful
spring:
main:
register-shutdown-hook: true # Ctrl+C and SIGTERM close the context
lifecycle:
timeout-per-shutdown-phase: 20s # how long running requests may take
server.shutdown=graceful
spring.main.register-shutdown-hook=true
spring.lifecycle.timeout-per-shutdown-phase=20s
The log of a graceful stop with one request still running:
INFO Commencing graceful shutdown. Waiting for active requests
INFO Graceful shutdown complete
INFO Web server stopped
Properties
| Key | Type | Default | Meaning |
|---|---|---|---|
server.shutdown |
graceful / immediate |
graceful |
How the server stops. |
spring.lifecycle.timeout-per-shutdown-phase |
Duration |
30s |
How long a graceful stop waits for running requests. A key of spring_boot_dart. |
spring.main.register-shutdown-hook |
bool |
false |
Close the context on SIGINT and SIGTERM. A key of spring_boot_dart. |
server.shutdown
- Type: enum. Default:
graceful.
| Value | What happens |
|---|---|
graceful |
No new connections. Running requests may finish, for up to spring.lifecycle.timeout-per-shutdown-phase. Then whatever is left is closed. |
immediate |
Every connection is closed at once. Running requests are cut: their clients see a broken connection. |
- Why change it:
immediatefor tests and tools that should stop fast. - Example:
server.shutdown=immediate. - Wrong value:
server.shutdown=neverstops the start with a binding failure that namesserver.shutdown.
spring.lifecycle.timeout-per-shutdown-phase
- Type:
Duration. Default:30s. - What it does here: the longest a graceful stop waits for the running requests.
- Also: it is the timeout of each phase of the context's lifecycle processor, as in Spring Boot. So the beans are destroyed only after the requests finished (or the time ran out). A request that still uses a database connection does not see the pool closed under it.
- Why change it: shorter when your platform kills the process sooner (Kubernetes sends SIGKILL after
terminationGracePeriodSeconds, 30 s by default: keep this key below it); longer when requests are long (reports, uploads). - Example:
spring.lifecycle.timeout-per-shutdown-phase=20s.
spring.main.register-shutdown-hook
- Type:
bool. Default:false(Spring Boot:true). - What it does: closes the context when the process gets SIGINT (
Ctrl+C) or SIGTERM (docker stop, Kubernetes). Then the server stops asserver.shutdownsays, and@PreDestroymethods run. VM only. - Without it, a signal ends the process at once: no graceful shutdown at all. Listening for signals keeps a Dart program alive, which is why it is off by default.
- Set it to
truein every server application.
What happens, step by step
- The context closes. Its lifecycle processor stops the
SmartLifecyclebeans phase by phase, highest phase first. The server's phase isSmartLifecycle.defaultPhase - 2048, so the beans of the default phase stop before it. - No new connections. The server closes its listening socket.
- Long-lived exchanges end now, in both modes:
- open WebSocket sessions are closed with
1001(going away), reasonServer stopping; - open event streams (
text/event-stream) and NDJSON streams (application/x-ndjson) are closed. They never end by themselves, so waiting for them would only use up the timeout. Browsers'EventSourcereconnects, to another instance.
- open WebSocket sessions are closed with
- Graceful: the server waits until every running request has finished and its response is out, and the connections are idle. It waits at most
spring.lifecycle.timeout-per-shutdown-phase.- When requests were running, it logs
Commencing graceful shutdown. Waiting for active requests, thenGraceful shutdown complete. - When the time runs out, it logs
Graceful shutdown aborted with one or more requests still activeand closes every connection by force. Those clients see a broken connection. - When no request was running, it closes without these lines.
- When requests were running, it logs
- Immediate: every connection is closed by force right away.
- Done.
Web server stoppedis logged. If stopping fails,Web server failed to stopis logged as a warning, and the shutdown goes on. - The beans are destroyed (
@PreDestroy,close()), after the phase finished.
A byte stream or a StreamingResponseBody is an ordinary request here: a graceful stop waits for it, within the timeout.
Rules and edge cases
- Running handlers are not interrupted by a graceful stop: Dart cannot stop running code. A request either finishes in time, or its connection is closed under it when the time runs out.
- A stop while the server is still starting waits for the socket to open, then closes it. No server is left listening.
- In a Flutter app the context pauses when the app goes to the background. The server stops in the same way (and frees its port), then starts again when the app comes back.
spring.flutter.lifecycle.pause-in-background=falsekeeps it running. - In tests,
server.shutdown=immediatemakes each test's context close faster when a test leaves a request open.
In Spring (Java)
server.shutdown=graceful
spring.lifecycle.timeout-per-shutdown-phase=20s
Differences that matter:
- The same keys and defaults. Graceful shutdown is the default, as in Spring Boot 3.4 and later.
spring.main.register-shutdown-hookisfalseby default. Set it, or signals end the process without a graceful stop.- Open event streams and WebSocket sessions are closed at the start of the shutdown, in both modes. In Spring they are left to the container.
- Spring Boot splits the work into two beans,
WebServerStartStopLifecycleandWebServerGracefulShutdownLifecycle. Here one bean,webServerStartStopLifecycle, does both.