In Spring MVC, HTTP responses are commonly built using the ResponseEntity class. While Spring automatically handles many HTTP headers for us, there are scenarios where we may need to explicitly set the Content-Length header, for example, when serving files, streaming binary data, or integrating with clients that rely on a precise content length.
This article explains what the Content-Length header is, when we should (and should not) set it manually, and multiple ways to set it in ResponseEntity using Spring MVC.
1. Understanding the Content Length Header
The Content-Length HTTP header indicates the exact size of the response body in bytes.
Content-Length: 1024
It allows clients to know when a response has been fully received, display accurate progress indicators during downloads, validate message integrity, and avoid chunked transfer encoding when it is not desired. In many cases, Spring automatically calculates this header, though manual control is sometimes required.
When Should You Set Content Length Manually?
You may want to explicitly set the Content Length header when returning a byte array or file resource, streaming data from a known source, working with proxies or clients that do not handle chunked encoding effectively, or when strict HTTP compliance is required for integrations.
You generally should not set the Content Length header manually when using streaming responses such as InputStreamResource or StreamingResponseBody, when allowing Spring to handle JSON or text responses automatically, or when the response size is unknown or dynamically determined.
2. Setting Content-Length Using HttpHeaders
A common and explicit way to set Content-Length is via HttpHeaders.
Example: Returning a Byte Array
@RestController
public class ContentLengthController {
@GetMapping("/data")
public ResponseEntity<byte[]> getData() {
byte[] data = "Hello, Spring MVC".getBytes(StandardCharsets.UTF_8);
HttpHeaders headers = new HttpHeaders();
headers.setContentLength(data.length);
headers.setContentType(MediaType.APPLICATION_OCTET_STREAM);
return new ResponseEntity<>(data, headers, HttpStatus.OK);
}
}
The setContentLength(long) method sets the header value, and the specified length must exactly match the number of bytes in the response body, as incorrect values can result in truncated responses or client-side errors.
3. Setting Content-Length Using the ResponseEntity Builder API
The ResponseEntity builder API provides an expressive way to construct HTTP responses while maintaining full control over headers, status codes, and the response body. Using this approach can improve readability and reduce boilerplate code, especially when setting common headers such as Content-Length alongside the response payload.
@GetMapping("/message")
public ResponseEntity<String> getMessage() {
String message = "Spring MVC ResponseEntity";
return ResponseEntity.ok()
.contentLength(message.getBytes(StandardCharsets.UTF_8).length)
.contentType(MediaType.TEXT_PLAIN)
.body(message);
}
4. Setting Content-Length When Returning Files
When serving files, explicitly setting the content length improves client compatibility.
@GetMapping("/download")
public ResponseEntity<byte[]> downloadFile() throws IOException {
Path path = Paths.get("download.pdf");
byte[] fileContent = Files.readAllBytes(path);
return ResponseEntity.ok()
.header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"download.pdf\"")
.contentType(MediaType.APPLICATION_PDF)
.contentLength(fileContent.length)
.body(fileContent);
}
In this example, the file is fully loaded into memory so its size is known in advance, allowing the Content-Length header to be set accurately. This ensures that clients can reliably determine the download size, display progress indicators, and complete the file transfer without relying on chunked encoding.
Using Resource Implementations
Spring provides several Resource implementations that are well-suited for serving files and binary content. Using a Resource allows Spring MVC to stream the response efficiently while still giving you control over important headers, such as Content-Length, when the underlying file size is known.
@GetMapping("/resource")
public ResponseEntity<Resource> getResource() throws IOException {
Path path = Paths.get("download.pdf");
Resource resource = new UrlResource(path.toUri());
long size = Files.size(path);
return ResponseEntity.ok()
.contentLength(size)
.contentType(MediaType.APPLICATION_PDF)
.header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"download.pdf\"")
.body(resource);
}
In this example, the file size is obtained directly from the filesystem, making it safe to set the Content-Length header explicitly. This approach balances efficient streaming with accurate metadata, enabling clients to handle downloads reliably while avoiding issues related to unknown or mismatched response sizes.
What About Streaming Responses?
For streaming responses such as InputStreamResource and StreamingResponseBody, you should avoid setting the Content-Length header manually unless the exact response size is known in advance. In these cases, Spring typically falls back to chunked transfer encoding, and providing an incorrect content length can lead to client errors or broken connections.
5. Common Pitfalls and Best Practices
When working with the Content-Length header, avoid setting a value that does not match the actual payload size, applying it to streaming responses with an unknown length, or assuming that string length is equivalent to byte length without considering character encoding. Always calculate the response size in bytes, not characters.
As a best practice, let Spring manage the Content-Length header whenever possible, set it explicitly only when the response size is known with certainty, use the ResponseEntity builder methods to improve readability, and validate the resulting headers with tools such as curl or Postman.
6. Conclusion
Setting the Content-Length header in Spring MVC is straightforward when using ResponseEntity. While Spring automatically manages this header in most cases, manual configuration is useful when serving files, binary data, or working with strict HTTP clients. By using HttpHeaders or the ResponseEntity builder API, we can safely and explicitly control the response size when needed while still leveraging Spring MVC’s flexible abstraction.
7. Download the Source Code
This article explained how to set the Content Length header in Spring MVC.
You can download the full source code of this example here: spring mvc set content length header
