Introduction

When Spring Boot file size limits seem to be ignored, the issue is often outside the property you changed. Upload limits can be enforced by Spring multipart settings, servlet container settings, reverse proxies, and custom multipart resolvers. To fix this reliably, verify each layer and test with real upload requests.

Correct Spring Boot Multipart Properties

In modern Spring Boot versions, use the spring.servlet.multipart namespace.

spring.servlet.multipart.enabled=true
spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=12MB

Equivalent YAML:

1spring:
2  servlet:
3    multipart:
4      enabled: true
5      max-file-size: 10MB
6      max-request-size: 12MB

If property names are wrong for your version, limits may silently stay at defaults.

Verify Controller and Request Mapping

Ensure endpoint actually receives multipart content.

1@RestController
2@RequestMapping("/api/files")
3public class UploadController {
4
5    @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
6    public ResponseEntity<String> upload(@RequestParam("file") MultipartFile file) {
7        return ResponseEntity.ok("size=" + file.getSize());
8    }
9}

If request is not multipart encoded, multipart limits do not apply as expected.

Conflicts with Custom Multipart Resolver

Custom beans can override auto configuration and bypass property based settings.

1@Bean
2public CommonsMultipartResolver multipartResolver() {
3    CommonsMultipartResolver resolver = new CommonsMultipartResolver();
4    resolver.setMaxUploadSize(10 * 1024 * 1024L);
5    return resolver;
6}

If you define a custom resolver, configure limits there too. Otherwise you may think Boot properties are ignored.

Embedded Container Limits and Proxy Limits

Even when Spring is configured correctly, upstream servers can reject large bodies first.

Examples:

• Nginx client_max_body_size
• API gateway request size limits
• load balancer body constraints

Nginx example:

server {
    client_max_body_size 12m;
}

If proxy limit is lower than Spring limit, request is rejected before it reaches your application.

Exception Handling and User Feedback

Configure exception handling so limit violations are visible and actionable.

1@RestControllerAdvice
2public class UploadExceptionHandler {
3
4    @ExceptionHandler(MaxUploadSizeExceededException.class)
5    public ResponseEntity<String> handleMaxSize(MaxUploadSizeExceededException ex) {
6        return ResponseEntity.status(HttpStatus.PAYLOAD_TOO_LARGE)
7                .body("Uploaded file is too large");
8    }
9}

Without explicit handling, users may see generic 500 errors that hide the real cause.

End to End Validation

Run upload tests with files below and above the configured limit.

curl -F "[email protected]" http://localhost:8080/api/files/upload
curl -F "[email protected]" http://localhost:8080/api/files/upload

Also check app logs and proxy logs to see which component rejected the request.

Version and Dependency Checks

If you upgraded Spring Boot, verify property namespaces and multipart dependencies. Old tutorials may reference deprecated property keys or resolver classes.

Keep dependency tree minimal. Multiple multipart libraries can lead to confusing behavior if auto configuration chooses an unexpected resolver.

Add Integration Tests for Size Limits

Automated integration tests should upload files around boundary values, including just below limit and just above limit cases. These tests detect regressions when proxy configuration or multipart resolver wiring changes. They also ensure your API consistently returns the expected status code and error payload for oversized uploads.

Keep these tests in CI so configuration drift is caught before production deployments.

Review limits after upgrades.

Common Pitfalls

• Using outdated property names that do not match the Spring Boot version in use.
• Defining a custom multipart resolver and forgetting to set limits in that resolver.
• Testing through a proxy with lower body size limits than the application.
• Forgetting that max-request-size must cover all multipart parts, not only one file.
• Returning generic server errors instead of clear payload too large responses.

Summary

• Start with correct spring.servlet.multipart configuration for your Boot version.
• Ensure endpoint consumes multipart form data and uses expected resolver path.
• Check proxy and gateway request limits, not only application settings.
• Add explicit exception handling for size violations.
• Validate end to end with real upload sizes and logs at each layer.