How to Use MultipartFile in Spring Boot for File Uploads

In Spring Boot, use MultipartFile to receive uploaded files in controller methods by annotating a parameter with @RequestParam. This allows you to access file data, name, and content type easily for processing or saving.

Syntax

The typical syntax to use MultipartFile in a Spring Boot controller method is:

• @PostMapping to handle POST requests.
• Method parameter annotated with @RequestParam("file") MultipartFile file to receive the uploaded file.
• Use file.getOriginalFilename() to get the file name.
• Use file.getBytes() or file.getInputStream() to read file content.

java

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;

@RestController
public class FileUploadController {

    @PostMapping("/upload")
    public String uploadFile(@RequestParam("file") MultipartFile file) {
        String fileName = file.getOriginalFilename();
        // process file
        return "File uploaded: " + fileName;
    }
}

Example

This example shows a complete Spring Boot controller that accepts a file upload, saves the file to a local folder, and returns a success message.

java

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;

import java.io.File;
import java.io.IOException;

@RestController
public class FileUploadController {

    private static final String UPLOAD_DIR = "uploads/";

    @PostMapping("/upload")
    public String uploadFile(@RequestParam("file") MultipartFile file) {
        if (file.isEmpty()) {
            return "No file selected to upload.";
        }
        try {
            File uploadDir = new File(UPLOAD_DIR);
            if (!uploadDir.exists()) {
                uploadDir.mkdirs();
            }
            String filePath = UPLOAD_DIR + file.getOriginalFilename();
            file.transferTo(new File(filePath));
            return "File uploaded successfully: " + file.getOriginalFilename();
        } catch (IOException e) {
            return "Failed to upload file: " + e.getMessage();
        }
    }
}

Output

File uploaded successfully: example.txt

Common Pitfalls

• Forgetting to add spring-boot-starter-web dependency to support multipart requests.
• Not configuring spring.servlet.multipart.enabled=true in application.properties if multipart support is disabled.
• Using @RequestBody instead of @RequestParam for MultipartFile parameter.
• Not setting enctype="multipart/form-data" in HTML form when uploading files.
• Ignoring file size limits configured by Spring Boot which can cause upload failures.

java

/* Wrong way: Using @RequestBody for MultipartFile (will not work) */
@PostMapping("/upload")
public String uploadFileWrong(@RequestBody MultipartFile file) {
    return "This will fail";
}

/* Right way: Use @RequestParam */
@PostMapping("/upload")
public String uploadFileRight(@RequestParam("file") MultipartFile file) {
    return "This works";
}

Quick Reference

Remember these key points when using MultipartFile in Spring Boot:

• Use @RequestParam("file") MultipartFile file in controller method.
• Set HTML form enctype="multipart/form-data" for file uploads.
• Use file.transferTo(new File(path)) to save files easily.
• Configure max file size in application.properties if needed.
• Check file.isEmpty() before processing.

Key Takeaways

Use @RequestParam with MultipartFile to receive uploaded files in Spring Boot controllers.

Always set enctype="multipart/form-data" in your HTML form for file uploads.

Use file.transferTo() to save uploaded files to disk easily.

Check if the file is empty before processing to avoid errors.

Configure multipart settings in application.properties to handle file size limits.