Timeouts
Three properties limit time: server.connection-timeout (the network is silent), server.request-timeout (the application is slow), and spring.mvc.async.request-timeout (an SseEmitter stays open).
Why
A server that waits forever can be held up by anyone:
- a client that starts to send a body and then sends nothing keeps a connection and a request open;
- idle keep-alive connections pile up;
- a handler that waits on a slow database or a slow remote service keeps its client waiting, and the client gave up long ago.
Each property covers one of these cases. They do not replace each other.
| Property | Limits | Default | Past it |
|---|---|---|---|
server.connection-timeout |
silence while a request body is read; idle keep-alive connections | 60s |
408, the connection closes; an idle connection closes |
server.request-timeout |
the time the filters and the handler take to start the answer | no limit | 503; the request's RequestDeadline has passed |
spring.mvc.async.request-timeout |
the life of an SseEmitter without its own timeout |
no limit | onTimeout callbacks, then the emitter completes |
Example
# lib/resources/application.yml
server:
connection-timeout: 30s
request-timeout: 10s
spring:
mvc:
async:
request-timeout: 30m
server.connection-timeout=30s
server.request-timeout=10s
spring.mvc.async.request-timeout=30m
A handler that reads the deadline between its steps:
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
@RestController()
@RequestMapping('/api/reports')
class ReportController {
ReportController(this.sales, this.stock);
final SalesClient sales; // a Feign client: it stops at the request's deadline
final StockService stock;
@GetMapping('/daily')
Future<Report> daily() async {
final totals = await sales.totals();
RequestDeadline.current?.check(); // nobody waits any more: stop here
final levels = await stock.levels();
return Report(totals, levels);
}
}
server.connection-timeout
- Type:
Duration(60s,500ms,PT1M; a plain number is milliseconds). Default:60s. - No limit:
0or any negative value (-1), as in Tomcat. - What it does, case 1: a stalled body. While a request body is read, the timer restarts with every chunk that arrives. When nothing arrives for this long, the read fails with a
408 Request TimeoutProblemDetail(detailThe request body did not arrive in time), and the connection closes after the answer. Time while the reader itself pauses (back-pressure) does not count. - What it does, case 2: idle connections. A keep-alive connection with no request for this long is closed. This is
dart:io'sidleTimeout. Tomcat's keep-alive timeout is also its connection timeout. - What it does not do: it does not limit a slow handler, a slow answer, or the total time of an upload that keeps sending. A handler is limited by
server.request-timeout. - Why change it: lower it (
10s) on a public server, so that silent clients free their connection sooner. Raise it for clients on very slow links that upload large files with long pauses. - Example:
server.connection-timeout=20s. - Careful:
server.connection-timeout=60is 60 milliseconds, not 60 seconds. Write the unit.
server.request-timeout
- Type:
Duration. Default: not set: no limit.0or a negative value: no limit either. - What it does: the filters and the handler must start the answer within this time. When the time passes first:
- the client gets
503 Service Unavailable, aProblemDetailwith the detailThe request did not complete in time.. It does not mention the limit or what the handler was doing; - whatever the handler does with the response afterwards is dropped: no second answer, no error;
- the 503 is logged as a warning, like other 5xx answers, at most once per 10 seconds for the same kind.
- the client gets
- The deadline. The request runs under a
RequestDeadlineof that length (fromspring_web_dart). It is carried in theZone, like a transaction, so it followsawaits. Code the request calls can read it:
| Member | What |
|---|---|
RequestDeadline.current |
the deadline of the code that runs now, or null |
budget |
the length it was given |
remaining |
the time left; never negative |
isExpired |
whether the time has passed |
check() |
throws a RequestDeadlineExceededException when the time has passed |
RequestDeadline.run(budget, body) |
runs body under a deadline of its own; inside another one, the earlier end wins |
- Feign clients honour it. A call a controller makes through a Feign client stops at the request's deadline: the limit of the call is the earlier of its own
call-timeoutand the time left. The call then throws, and the request is answered with the 503. - Errors at the deadline are a 503. A
RequestDeadlineExceededException, or any error thrown in the last 10 ms of the deadline, is answered with the 503 (also aRequestDeadlineExceededExceptionthrown by aRequestDeadline.runof your own without the property). Other errors keep their own answer (a 400, a 500). - Filters count. The filters (the security filter chain too) run inside the budget. Time a filter uses is taken from the handler.
- Why change it: a public API whose clients give up after some seconds anyway; a backend whose callers have their own timeout (set it a little below theirs); to stop slow remote calls from piling up.
- Example:
server.request-timeout=10s.
What it does not do
- It does not stop running code. Dart cannot interrupt a function. A handler that never reads the deadline runs on after the 503; its late answer is dropped. Call
RequestDeadline.current?.check()between steps, or use clients that read the deadline. - Streams are not cut. A response that starts to stream (server-sent events, an
SseEmitter, NDJSON, a byte stream, aStreamingResponseBody) leaves the deadline when it starts. What the stream does later runs under no deadline. Usespring.mvc.async.request-timeoutorSseEmitter(timeout:)for event streams. - A response already being sent is left alone. Once the status and headers are out, the timer does nothing.
- WebSocket handshakes are not timed.
@ExceptionHandlermethods do not see this 503, because the handler is still running.- Uploads count. The time the handler spends reading a slow upload counts.
server.connection-timeoutstill ends a body that sends nothing. - One value for all requests. There is no per-route value yet.
- Not in a customizer. The dispatcher reads it from the property. A
WebServerFactoryCustomizercannot change it.
spring.mvc.async.request-timeout
- Type:
Duration. Default: not set: no limit. - What it does: the timeout of an
SseEmittercreated without one (SseEmitter()). It counts from when the response starts. When it passes, the emitter'sonTimeoutcallbacks run, then the emitter completes and the stream ends. - An emitter with its own timeout (
SseEmitter(timeout: const Duration(minutes: 5))) keeps it. - A
StreamorEventStreamresult is not limited by it. It ends when the stream ends, when the client goes away, or when the server stops. - Why change it: give every emitter a maximum life, so that forgotten emitters do not stay open forever. Browsers'
EventSourcereconnects by itself. - Example:
spring.mvc.async.request-timeout=30m.
@GetMapping('/api/orders/updates')
SseEmitter updates() {
final emitter = SseEmitter(); // ends after spring.mvc.async.request-timeout
emitter.onTimeout(() => emitter.send('bye'));
orders.watch(emitter);
return emitter;
}
See Server-sent events.
How they work together
- A client uploads a 50 MB file over a slow link and pauses for 2 minutes:
server.connection-timeout(60 s) ends it with a 408. - The same upload keeps sending, but takes 3 minutes in all, with
server.request-timeout=30s: the 503 comes at 30 s, because the handler that reads the body has not answered yet. - A handler waits 20 s for a Feign call, with
server.request-timeout=10s: the call stops at 10 s, and the client gets the 503. - An event stream stays open for an hour, with
server.request-timeout=10s: it is not cut, because it left the deadline when it started. Withspring.mvc.async.request-timeout=30m, anSseEmitterends after 30 minutes. - A client keeps a connection open without sending a request: it closes after
server.connection-timeout.
At shutdown, spring.lifecycle.timeout-per-shutdown-phase limits how long running requests may still take. See Shutdown.
In Spring (Java)
server.tomcat.connection-timeout=30s
spring.mvc.async.request-timeout=30m
Differences that matter:
server.connection-timeoutis the key Spring Boot 2.0 had. Spring Boot 3 and 4 useserver.tomcat.connection-timeout(or Jetty's and Undertow's keys).- A stalled body gets a 408 here. With Tomcat the read fails and Spring answers 400.
server.request-timeoutandRequestDeadlineare extensions. Spring has no limit for synchronous requests, and no limit follows a request into the calls it makes.spring.mvc.async.request-timeoutapplies only toSseEmitters here. In Spring it applies to every asynchronous request (DeferredResult,Callable,ResponseBodyEmitter), and without it the container's default (Tomcat: 30 seconds) applies. Here, without it, an emitter never times out.