MaxUploadSizeExceededException: Maximum upload size exceeded

Q: Increase multipart limits in properties

When to use: Use this if your app legitimately requires larger file uploads.. Spring Boot limits file uploads to 1MB by default to prevent Denial of Service attacks. Increase this limit to match your business needs.

Q: Handle the exception globally

When to use: Use this to return a clean 400 Bad Request JSON instead of a 500 Tomcat error page.. Create a global exception handler to catch MaxUploadSizeExceededException and return a friendly message.

Q: Stream the file upload directly

When to use: Use this for massive files (gigabytes) where you don't want to load the whole file into memory.. Use InputStream or MultipartFile.transferTo() to stream chunks directly to disk or cloud storage, bypassing Spring's size limits.

🔴 The Error You're Seeing

Confirm this matches your console output. If it does, you're in the right place.

ERROR LOG

2026-02-14 10:15:20.100 ERROR 8842 --- [nio-8080-exec-2] o.a.c.c.C.[.[.[/].[dispatcherServlet]    : Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed: org.springframework.web.multipart.MaxUploadSizeExceededException: Maximum upload size exceeded; nested exception is java.lang.IllegalStateException: org.apache.tomcat.util.http.fileupload.FileUploadBase$SizeLimitExceededException: the request was rejected because its size (10485760) exceeds the configured maximum (1048576)]

⚡ Quick Fix Works 80% of the time

Increase the spring.servlet.multipart.max-file-size in application.properties.

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

🧠 Why this Happens

Tap to expand the deep technical explanation

Spring Boot's embedded Tomcat server has a default limit of 1MB for multipart file uploads to protect the server from running out of memory. A client attempted to upload a file larger than this configured limit.

The HITEC City Parking Spot Analogy:

It is like trying to fit an elephant into a tiny car trunk. The car (server) has a fixed capacity, and if the object (file) is too big, it simply won't fit and breaks the hinges.

🔁 How to Reproduce Confirm this is your error

POST a file larger than the default 1MB multipart limit to a @RequestParam MultipartFile endpoint. Spring throws MaxUploadSizeExceededException: Maximum upload size exceeded.

🛠️ Solutions (3 Ways to Fix)

Solution 1✓ Most common cause

Increase multipart limits in properties

👉 Use this if your app legitimately requires larger file uploads.

Spring Boot limits file uploads to 1MB by default to prevent Denial of Service attacks. Increase this limit to match your business needs.

# application.properties
spring.servlet.multipart.max-file-size=50MB
spring.servlet.multipart.max-request-size=50MB

Solution 2

Handle the exception globally

👉 Use this to return a clean 400 Bad Request JSON instead of a 500 Tomcat error page.

Create a global exception handler to catch MaxUploadSizeExceededException and return a friendly message.

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MaxUploadSizeExceededException.class)
    public ResponseEntity<String> handleMaxSizeException(MaxUploadSizeExceededException ex) {
        return ResponseEntity.status(HttpStatus.PAYLOAD_TOO_LARGE).body("File size exceeds the 50MB limit!");
    }
}

Solution 3

Stream the file upload directly

👉 Use this for massive files (gigabytes) where you don't want to load the whole file into memory.

Use InputStream or MultipartFile.transferTo() to stream chunks directly to disk or cloud storage, bypassing Spring's size limits.

@PostMapping("/upload")
public void upload(@RequestParam("file") MultipartFile file) throws IOException {
    // Stream directly to disk without loading into memory
    file.transferTo(Path.of("/uploads/" + file.getOriginalFilename()));
}

📋 Version Notes

Spring Boot 2.x

Throws MaxUploadSizeExceededException with 500 status if not handled.

Spring Boot 3.x

Throws MaxUploadSizeExceededException, but Tomcat 10 enforces limits slightly earlier in the cycle.

🛡️ How to Prevent This Next Time

Set realistic file size limits based on your app's requirements, and implement frontend validation to reject large files before the upload starts.