[SpringBoot - SSR] 파일 업로드 에러: "Failed to convert String to MultipartFile" 원인과 해결

Spring Boot로 파일 업로드 기능을 구현하다 보면, 꽤 긴 에러 메시지와 함께 요청이 실패하는 경험을 하게 됩니다. 특히 폼(Form) 데이터를 통해 이미지를 전송할 때, 분명 파일을 선택했음에도 불구하고 서버 로그에는 타입 변환 실패(Type Mismatch) 오류가 찍히는 경우가 빈번합니다.

오늘은 파일 업로드 구현 시 가장 흔하게 발생하는 MultipartFile typeMismatch 에러의 정확한 원인과, 이를 해결하기 위한 체크리스트를 정리해 보려 합니다.

 

[SpringBoot - SSR] 파일 업로드 에러:

 "Failed to convert String to MultipartFile" 원인과 해결

 

 

 

Spring Boot에서 처음 파일 업로드 기능을 구현하다 보면,, 아래와 같은 에러 로그를 한 번쯤은 반드시 마주하게 됩니다.

 

Failed to convert property value of type 'java.lang.String' 
to required type 'org.springframework.web.multipart.MultipartFile'

 

에러 메시지는 길고 복잡하지만, 원인은 생각보다 단순... 이 글에서는 해당 에러가 발생하는 정확한 이유와, 실무에서 어떻게 해결하는지 단계적으로 정리하려 합니당.

---

1. 에러 상황 요약

다음과 같은 로그가 출력된다고 가정!

Field error in object 'mentor' on field 'file': rejected value [002.png]
Cannot convert value of type 'java.lang.String' 
to required type 'MultipartFile'

 

여기서의 핵심은 

Spring이 String 값을 MultipartFile로 변환하려다 실패했다

즉, 서버는 파일을 기대했는데 실제로는 문자열이 넘어왔다는 뜻../

 

 

---

 

2. MultipartFile은 언제 정상적으로 바인딩될까?

 

Spring에서 MultipartFile이 정상적으로 바인딩되려면 반드시 아래 조건을 만족해야 합니다.

1. HTML form의 enctype이 multipart/form-data일 것
2. 요청 방식이 POST일 것
3. input 타입이 file일 것
4. Controller에서 MultipartFile로 직접 받거나 DTO에 포함되어 있을 것

이 중 하나라도 어기면 Spring은 파일이 아닌 문자열로 인식해버림.

 

 

---

 

3. 가장 흔한 원인 ① enctype 누락

 

잘못된 HTML 폼 

<form method="post">
    <input type="file" name="file" />
</form>

이 경우 브라우저는 파일을 바이너리로 보내지 않고, 단순 문자열로 전송한다.

해당 에러를 겪은 프로젝트는 SSR 프로젝트 였습니다.

올바른 HTML 폼

<form method="post" enctype="multipart/form-data">
    <input type="file" name="file" />
</form>

 

enctype="multipart/form-data"는 파일 업로드에서 필수

 

---

 

4. 가장 흔한 원인 ② DTO에 String 필드가 남아 있는 경우

 

다음과 같은 DTO 구조는 매우 위험함...

public class MentorDTO {
    private String file;
}

폼에서는 파일을 업로드했지만, DTO에서는 String으로 받도록 되어 있다면 Spring은 문자열로 바인딩을 시도하게됨 ㅜ

 

올바른 DTO

public class MentorDTO {
    private MultipartFile file;
}

 

DTO 필드 타입과 실제 전송 타입이 반드시 일치해야 합니다.

 

---

 

5. 원인 ③ 수정 페이지에서 기존 파일명을 그대로 보내는 경우

 

수정(edit) 화면에서 자주 발생하는 케이스

<input type="hidden" name="file" value="002.png" />

이 상태에서 Controller는 다음과 같이 생겼다면

@PostMapping("/edit")
public String edit(@ModelAttribute MentorDTO dto) {
    // ...
}

Spring은 file = "002.png"라는 문자열을 MultipartFile로 변환하려다 실패해버림

 

해결 방법

 

• 기존 파일명은 별도의 필드로 관리
• 파일 업로드 필드는 새로 업로드할 때만 사용

private MultipartFile file;      // 새 파일
private String originFileName;   // 기존 파일명

---

6. Controller에서 가장 안전한 방식

 

DTO 바인딩이 헷갈린다면, Controller에서 명시적으로 분리하는 것도 좋은 방법입니다

 

@PostMapping("/add")
public String add(@ModelAttribute MentorDTO dto,
                  @RequestParam("file") MultipartFile file) {
    // 파일 처리
}

이 방식은 디버깅이 쉽고, 타입 미스매치 문제를 빠르게 잡을 수 있다!!

 

---

 

7. typeMismatch 에러가 발생하는 근본 이유

 

정리하면 이 에러의 본질은 단 하나

Spring은 자동 변환을 해주지 않는다.
String은 String이고, MultipartFile은 MultipartFile이다.

 

파일 업로드는 일반 form 데이터와 완전히 다른 처리 경로를 탑니다

---

 

8. 체크리스트

 

에러가 발생하면 아래 순서대로 점검하면 된다.

1. form에 enctype="multipart/form-data"가 있는가
2. input 타입이 file인가
3. DTO 필드 타입이 MultipartFile인가
4. 수정 화면에서 hidden input으로 파일명을 보내고 있지는 않은가
5. Controller에서 String과 MultipartFile을 혼용하고 있지는 않은가

(경험 상... )

 

---

 

9. 정리

• MultipartFile typeMismatch 에러는 구조 문제다
• Spring의 자동 변환 문제가 아니다
• HTML, DTO, Controller 중 하나만 어긋나도 바로 터진다

파일 업로드는 명시적으로, 단순하게 구성하는 것이 가장 안전합니다!

 

파일 업로드는 데이터의 흐름이 일반 텍스트 전송과는 다르기 때문에, 데이터가 흘러가는 파이프라인(HTML -> HTTP Request -> DispatcherServlet -> Controller)을 명확히 이해하고 구현하는 것이 중요합니다!

 

 

해당 게시물은 멘토링 웹사이트 개발 , SSR 프로젝트 에서 겪은 경험으로 깃허브를 통해 확인할 수 있습니다.