Introduction

StreamingResponseBody is useful when you want to send data to the client incrementally instead of buffering the whole response in memory. The timeout behavior is different from normal controller responses because the request may stay open for a long time while bytes are still being written. To control this reliably, you need to think about async request timeout, container timeout, and the pace of the stream itself.

How StreamingResponseBody Changes the Request Lifecycle

A StreamingResponseBody controller hands work off to an async response pipeline. That means a normal synchronous request timeout is no longer the whole story. Spring MVC’s async timeout and the servlet container’s connection behavior both matter.

Basic streaming endpoint:

1import org.springframework.http.MediaType;
2import org.springframework.web.bind.annotation.GetMapping;
3import org.springframework.web.bind.annotation.RestController;
4import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody;
5
6import java.io.OutputStream;
7import java.nio.charset.StandardCharsets;
8
9@RestController
10public class StreamController {
11
12    @GetMapping(value = "/stream", produces = MediaType.TEXT_PLAIN_VALUE)
13    public StreamingResponseBody stream() {
14        return outputStream -> {
15            for (int i = 0; i < 5; i++) {
16                outputStream.write(("chunk-" + i + "\\n").getBytes(StandardCharsets.UTF_8));
17                outputStream.flush();
18                Thread.sleep(1000);
19            }
20        };
21    }
22}

As long as the stream is actively writing and the infrastructure permits it, the response remains open.

Configure Spring MVC Async Timeout

Spring MVC has an async request timeout that applies to async processing, including streaming handlers.

1import org.springframework.context.annotation.Configuration;
2import org.springframework.web.servlet.config.annotation.AsyncSupportConfigurer;
3import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
4
5@Configuration
6public class WebConfig implements WebMvcConfigurer {
7    @Override
8    public void configureAsyncSupport(AsyncSupportConfigurer configurer) {
9        configurer.setDefaultTimeout(30_000L);
10    }
11}

This sets a default async timeout of 30 seconds. If the stream takes longer without completing or progressing appropriately, Spring can terminate it.

Per-Endpoint Timeout Strategy

If different endpoints need different time budgets, a one-size global timeout may be too blunt. In those cases, consider separating long-lived streaming endpoints behind distinct configuration, controller path groups, or infrastructure routing.

For example:

• short-lived CSV export stream: tens of seconds
• server-sent events: minutes or effectively long-lived
• video or large object download: infrastructure-managed timeout

The correct timeout depends on the product contract, not only framework defaults.

Executor and Backpressure Matter

StreamingResponseBody uses async execution. If the async executor is under-provisioned, requests can appear to hang even before timeout logic becomes relevant. Configure an executor that matches expected concurrency and workload pattern.

Also note that client read speed matters. A stream that writes slowly because the downstream client is slow can hold resources much longer than expected.

Container and Proxy Timeouts Still Apply

Even if Spring timeout is generous, the servlet container, reverse proxy, or load balancer may close the connection earlier. In production, you need alignment across:

• Spring async timeout
• embedded Tomcat or Jetty settings
• proxy idle timeout
• client expectations

If one layer has a much shorter idle timeout than the others, your stream may terminate unexpectedly despite correct application code.

Failure Handling Inside the Stream

Streaming code should handle disconnects and interrupted writes cleanly.

1return outputStream -> {
2    try {
3        for (int i = 0; i < 10; i++) {
4            outputStream.write(("line-" + i + "\\n").getBytes(StandardCharsets.UTF_8));
5            outputStream.flush();
6            Thread.sleep(500);
7        }
8    } catch (Exception ex) {
9        // Log and stop streaming. The client may already be gone.
10        System.err.println("stream failed: " + ex.getMessage());
11    }
12};

Do not assume every broken stream is an application bug. Client disconnects are normal in long-lived endpoints.

Choose the Right Abstraction

If you are actually building continuous event feeds, consider server-sent events or reactive endpoints rather than forcing everything through StreamingResponseBody. Timeouts are easier to reason about when the transport model matches the product behavior.

Common Pitfalls

• Configuring only one timeout layer and ignoring proxy or container limits.
• Using StreamingResponseBody for long-lived event streams without checking if SSE or reactive streaming is a better fit.
• Forgetting async executor sizing and blaming timeout settings for worker starvation.
• Assuming “streaming” means timeout-free behavior.
• Not flushing output when incremental delivery is required.

Summary

• 'StreamingResponseBody uses Spring MVC async processing, so async timeout settings matter.'
• Configure Spring timeout, but also align container and proxy timeouts.
• Size async executors for the expected stream workload.
• Handle client disconnects and partial-stream failures explicitly.
• Use a streaming abstraction that matches the endpoint’s actual delivery model.