Introduction

If CommonMultipartResolver or Apache Commons FileUpload classes are missing when you try to set maxUploadSize, you are usually mixing old Spring MVC examples with modern Spring Boot configuration. In current Spring Boot applications, the normal fix is to stop configuring the Commons resolver and use Boot's built-in multipart support instead.

Why the Exception Happens

Older tutorials often show a bean like CommonsMultipartResolver and then call setMaxUploadSize(...). That worked in older Spring MVC setups that depended on Apache Commons FileUpload. In a typical Spring Boot application, however, multipart handling is auto-configured around the servlet Part API.

So this pattern often fails:

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

The failure means one of two things:

• the Apache Commons FileUpload classes are not on the classpath
• you are following an outdated approach for the Spring Boot version you are using

In modern Spring Framework releases, StandardServletMultipartResolver is the main supported resolver. That is why current Boot documentation points you toward configuration properties instead of a custom Commons bean.

Recommended Fix in Spring Boot

For most projects, remove the custom multipart resolver bean and configure limits in properties or YAML.

1spring:
2  servlet:
3    multipart:
4      max-file-size: 10MB
5      max-request-size: 25MB

Then your controller can stay simple:

1import org.springframework.http.ResponseEntity;
2import org.springframework.web.bind.annotation.PostMapping;
3import org.springframework.web.bind.annotation.RequestParam;
4import org.springframework.web.bind.annotation.RestController;
5import org.springframework.web.multipart.MultipartFile;
6
7@RestController
8public class UploadController {
9
10    @PostMapping("/upload")
11    public ResponseEntity<String> upload(@RequestParam("file") MultipartFile file) {
12        return ResponseEntity.ok(
13            "Received " + file.getOriginalFilename() + " with " + file.getSize() + " bytes"
14        );
15    }
16}

This is the approach that best matches how Spring Boot auto-configuration works. You do not need CommonsMultipartResolver just to set upload size limits.

What to Do in Legacy Applications

If you are maintaining an older application that truly depends on Apache Commons FileUpload, then you need the matching dependency and configuration style for that older stack.

For Maven, that might look like:

1<dependency>
2  <groupId>commons-fileupload</groupId>
3  <artifactId>commons-fileupload</artifactId>
4  <version>1.5</version>
5</dependency>

And then the legacy bean becomes valid:

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

That is a compatibility path, not the default recommendation for a new Boot application.

Handling Upload Errors Cleanly

Whichever resolver strategy you use, you should translate upload-size failures into a clear response. Otherwise users see an unhelpful server error.

1import org.springframework.http.HttpStatus;
2import org.springframework.http.ResponseEntity;
3import org.springframework.web.bind.annotation.ControllerAdvice;
4import org.springframework.web.bind.annotation.ExceptionHandler;
5import org.springframework.web.multipart.MaxUploadSizeExceededException;
6
7@ControllerAdvice
8public class UploadExceptionHandler {
9
10    @ExceptionHandler(MaxUploadSizeExceededException.class)
11    public ResponseEntity<String> handleTooLarge(MaxUploadSizeExceededException ex) {
12        return ResponseEntity
13            .status(HttpStatus.PAYLOAD_TOO_LARGE)
14            .body("Upload rejected because it exceeds the configured limit.");
15    }
16}

That does not solve the ClassNotFoundException, but it completes the upload flow once the resolver is configured correctly.

How to Decide Which Path You Are On

Ask two simple questions:

1. Am I building a current Spring Boot application?
2. Do I actually need Apache Commons FileUpload-specific behavior?

If the answer to the first is yes and the second is no, use spring.servlet.multipart.* properties and remove the custom resolver bean.

If the codebase is older and already built around Commons FileUpload, then keep that path but make sure the dependency matches the framework version and the bean name is multipartResolver.

Common Pitfalls

The most common mistake is copying a pre-Boot or old Boot example into a modern application and assuming multipart configuration still works the same way.

Another mistake is adding a custom resolver bean without understanding that Boot already auto-configures multipart support. That can create confusion even when it does not throw immediately.

People also forget that file-size properties and bean-based byte limits are different styles. Mixing them without a clear reason makes the application harder to maintain.

Finally, if you are on a recent Spring stack, be careful with old imports and examples that rely on classes no longer present in the current framework line.

Summary

• 'ClassNotFoundException here usually means an outdated multipart configuration approach.'
• In modern Spring Boot, prefer spring.servlet.multipart.max-file-size and max-request-size.
• Use MultipartFile with Boot's built-in multipart support instead of forcing CommonsMultipartResolver.
• Only add Apache Commons FileUpload for legacy applications that explicitly depend on it.
• Handle oversized uploads with an exception handler so the runtime behavior stays clear.