Spring Boot MultipartFile 예외 해결법

소개

파일 업로드는 웹 애플리케이션에서 흔한 기능이지만 설정 하나만 잘못돼도 MultipartFile 관련 예외가 잦게 발생한다. 본문에서는 빈번한 오류 원인과 점검 항목, 설정 방법, 예외 처리 코드를 예제로 정리한다. 처음 접하는 개발자도 이해하기 쉽게 단계별로 설명한다.

자주 발생하는 예외와 원인

1) MultipartFile이 null로 들어오는 문제

가장 흔한 현상은 컨트롤러에서 MultipartFile 파라미터가 null로 전달되는 경우다. 주요 원인은 다음과 같다.

• 클라이언트 폼에 enctype="multipart/form-data"가 빠짐
• 파라미터 이름이 일치하지 않음 (예: file vs upload)
• @RequestPart와 @RequestParam 사용 혼동
• 파일 크기 제한 초과로 파서에서 파일을 버림

2) MultipartException / MaxUploadSizeExceededException

업로드 허용 크기보다 큰 파일 업로드 시 발생한다. 스프링은 내부적으로 MaxUploadSizeExceededException을 발생시키며, 이를 적절히 처리하지 않으면 500 에러가 반환된다.

3) MissingServletRequestPartException

요청에 필수 파트가 없을 때 발생한다. 컨트롤러에서 required=true로 지정된 파트가 존재하지 않으면 이 예외가 던져진다.

4) Content-Type 관련 문제

클라이언트가 올바른 Content-Type을 보내지 않으면 서버가 multipart로 인식하지 못한다. AJAX 요청이나 폼 전송 시 헤더를 확인해야 한다.

설정 점검

application.properties 또는 application.yml에서 multipart 관련 설정을 확인한다. 대표 설정은 파일 최대 크기와 요청 최대 크기다.

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

프록시나 로드밸런서(Nginx 등)를 사용하는 경우에는 서버 쪽 설정도 함께 점검한다. Nginx의 client_max_body_size가 작으면 스프링까지 도달하기 전에 차단된다.

컨트롤러 구현 예시

올바른 시그니처와 기본적인 검증을 넣으면 문제 발생 확률을 낮출 수 있다.

@RestController
public class FileController {

  @PostMapping("/upload")
  public ResponseEntity<String> upload(@RequestParam("file") MultipartFile file) {
    if (file == null || file.isEmpty()) {
      return ResponseEntity.badRequest().body("파일이 비어있음");
    }
    // 파일 저장 로직 예시
    try {
      String original = file.getOriginalFilename();
      // 저장 처리
      return ResponseEntity.ok("업로드 성공: " + original);
    } catch (IOException e) {
      return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("저장 실패");
    }
  }
}

주의사항:

• 폼 필드 이름과 @RequestParam 이름을 일치시킨다.
• AJAX 전송 시 FormData를 사용하고 Content-Type을 브라우저가 자동 설정하도록 한다.

예외 처리 전략

글로벌 예외 처리로 공통 응답을 정의하면 디버깅이 쉬워진다. 아래는 MultipartException과 MaxUploadSizeExceededException을 처리하는 예시다.

@ControllerAdvice
public class GlobalExceptionHandler {

  @ExceptionHandler(MaxUploadSizeExceededException.class)
  public ResponseEntity<String> handleMaxSize(MaxUploadSizeExceededException ex) {
    return ResponseEntity.status(HttpStatus.PAYLOAD_TOO_LARGE).body("파일 크기 초과");
  }

  @ExceptionHandler(MultipartException.class)
  public ResponseEntity<String> handleMultipart(MultipartException ex) {
    return ResponseEntity.badRequest().body("멀티파트 처리 오류: " + ex.getMessage());
  }

  @ExceptionHandler(MissingServletRequestPartException.class)
  public ResponseEntity<String> handleMissingPart(MissingServletRequestPartException ex) {
    return ResponseEntity.badRequest().body("필수 파일 누락: " + ex.getRequestPartName());
  }
}

문제 발생 시 점검 체크리스트

• 클라이언트 폼에 enctype이 multipart/form-data인지 확인
• 파라미터 이름 일치 여부 확인
• application.properties의 max-file-size와 max-request-size 확인
• 웹서버(Nginx, Apache) 업로드 제한 확인
• Ajax 전송 시 FormData 사용 및 Content-Type 자동 설정 확인
• 컨트롤러에서 file.isEmpty()로 빈 파일 방지
• 글로벌 예외 핸들러로 오류 응답 통일

실제 사례와 해결 흐름

예를 들어 파일이 null로 들어오면 먼저 HTML form의 enctype과 입력 요소 name을 확인한다. 브라우저 측 이상이 없으면 서버 로그와 스프링 설정을 체크한다. 만약 로그에 MaxUploadSizeExceededException이 보이면 설정을 늘리거나 클라이언트 제한을 안내한다. 이런 흐름을 유지하면 문제를 빠르게 좁힐 수 있다.

결론

MultipartFile 관련 예외는 대부분 설정·요청 구성·파라미터 불일치에서 기인한다. 기본 설정을 점검하고, 컨트롤러에서 검증을 추가하며, 글로벌 예외 처리를 두면 안정적으로 처리할 수 있다. 필요 시 웹서버 제한도 함께 확인하면 문제 해결 속도가 빨라진다.

참고 키워드

검색 및 문제 해결에 도움이 되는 키워드: multipartfile null exception spring boot, multipart exception 해결 spring boot, file upload error spring boot.