안녕하세요, 여러분의 든든한 IT 길잡이 데브프리입니다.
게시판에 '첨부파일' 기능이나 마이페이지의 '프로필 이미지 업로드' 기능을 며칠 밤을 새워 완성했습니다. 구글에서 다운받은 귀여운 100KB짜리 아이콘으로 테스트했을 때는 아주 완벽하게 서버에 저장이 되었습니다.
"좋아, 완벽해! 이제 실전 테스트다!"
하고 스마트폰으로 찍은 5MB짜리 고화질 사진을 올리는 순간... 브라우저는 뻗어버리고 서버 콘솔 창에는 붉은 에러가 길게 쏟아집니다.
org.springframework.web.multipart.MaxUploadSizeExceededException: Maximum upload size exceeded
"아니, 코드는 똑같은데 왜 작은 파일은 되고 큰 파일은 안 되는 거지?"
초보 백엔드 개발자들이 파일 업로드 기능을 구현할 때 100% 마주치는 이 에러! 오늘은 '파일 용량 초과 에러'의 원인을 공항의 수하물 시스템에 비유하여 알아보고, 아주 간단하게 설정 파일 한 줄로 해결하는 방법을 정리해 드리겠습니다.
1. MaxUploadSizeExceededException, 도대체 왜 뜨는 걸까? (공항 수하물 비유)
에러 메시지를 해석해 보면 "최대 업로드 허용 사이즈를 초과했습니다"라는 뜻입니다.
여러분이 공항에서 비행기를 탈 때, 아무리 비싼 티켓을 샀어도 100kg짜리 쇳덩이 캐리어를 비행기에 실을 수는 없습니다. 비행기의 안전(서버의 메모리)을 위해 1인당 15kg이라는 '수하물 제한'이 있기 때문이죠.
스프링 부트(Spring Boot)에 내장된 웹 서버(Tomcat)도 마찬가지입니다. 악성 유저가 100GB짜리 영화 파일을 1,000번 연속으로 업로드해서 서버의 하드디스크를 터뜨리는 공격(DDoS)을 막기 위해, 초기 설정으로 아주 깐깐한 용량 제한을 걸어두었습니다.
- 스프링 부트의 기본 제한: 파일 1개당 최대 1MB, 요청 1번당 최대 10MB
요즘 스마트폰으로 찍은 사진 한 장이 기본 3~5MB를 훌쩍 넘는데, 서버는 1MB까지만 받겠다고 문을 닫아버리니 충돌이 날 수밖에 없었던 것입니다!
2. 해결 방법: application.properties 설정 변경 (무게 제한 늘리기)
이 에러는 코드를 뜯어고칠 필요가 없습니다. 공항 카운터 직원(스프링 부트)에게 "이제부터 VIP 손님들이 올 거니까 수하물 제한을 10MB로 늘려주세요!"라고 설정만 바꿔주면 됩니다.
src/main/resources 폴더 아래에 있는 application.properties (또는 application.yml) 파일을 열고 아래 코드를 추가해 줍니다.
⚙️ application.properties를 쓰는 경우
# 💡 파일 1개당 허용할 최대 용량 (기본값 1MB)
spring.servlet.multipart.max-file-size=10MB
# 💡 1번의 요청(여러 개 파일 합산)에 허용할 최대 용량 (기본값 10MB)
spring.servlet.multipart.max-request-size=50MB
⚙️ application.yml을 쓰는 경우
spring:
servlet:
multipart:
max-file-size: 10MB
max-request-size: 50MB
- max-file-size: 캐리어 '하나'의 최대 무게 제한입니다.
- max-request-size: 일가족 전체가 가져온 캐리어들의 '총합' 무게 제한입니다. (보통 단일 파일 제한보다 넉넉하게 잡아줍니다.)
이렇게 설정한 뒤 서버를 재시작하고 다시 5MB짜리 사진을 업로드해 보세요. 에러 없이 깔끔하게 서버에 저장되는 것을 확인할 수 있습니다!
3. 🚨 실무 꿀팁: 서버에 배포했는데 또 에러가 난다고요? (Nginx 413 에러)
로컬(내 컴퓨터)에서는 위 설정으로 완벽하게 고쳤는데, AWS 같은 실제 서버에 배포하고 나니 413 Request Entity Too Large 라는 에러가 뜨면서 또 파일이 안 올라가는 경우가 있습니다.
이것은 스프링 부트의 잘못이 아닙니다! 실무에서는 주로 스프링 부트 앞에 Nginx(엔진엑스)라는 문지기(리버스 프록시)를 세워두는데, 이 문지기 녀석의 기본 수하물 제한도 1MB이기 때문입니다. 스프링 부트에 도달하기도 전에 Nginx 문지기 선에서 컷을 당한 것이죠.
[Nginx 해결법] Nginx 설정 파일(nginx.conf 또는 default.conf)을 열어 http 블록이나 server 블록 안에 아래 코드를 한 줄 추가해야 합니다.
# Nginx 문지기야, 파일 용량을 50MB까지 통과시켜 줘!
client_max_body_size 50M;
저장 후 sudo systemctl restart nginx 로 재시작해 주면 실서버에서도 완벽하게 업로드가 작동합니다!
4. 요약: 트러블슈팅 체크리스트
파일 업로드 중 용량 에러가 터졌다면 아래 3가지를 순서대로 체크하세요.
- 에러 로그 확인: MaxUploadSizeExceededException 이 맞는지 콘솔을 확인합니다.
- 스프링 부트 설정: application.properties 에서 max-file-size 와 max-request-size 를 서비스 규모에 맞게 (예: 10MB, 50MB) 넉넉히 늘려줍니다.
- 실서버 Nginx 점검 (배포 시): 로컬은 되는데 배포 환경에서 413 에러가 뜬다면, Nginx 설정 파일에 client_max_body_size를 추가했는지 확인합니다.
마무리
기능 개발을 하다 보면 내 컴퓨터의 테스트 환경과 실제 유저들이 사용하는 환경(고화질 사진, 대용량 파일 등)의 차이로 인해 겪는 에러가 참 많습니다.
무작정 용량 제한을 '1GB'처럼 거대하게 열어두는 것은 서버 보안과 디스크 비용 측면에서 매우 위험합니다. 여러분이 기획한 서비스(프로필 사진용인지, 대용량 영상 첨부용인지)에 딱 맞는 적절한 용량 제한 값을 고민해 보는 센스 있는 개발자가 되시길 바랍니다!
오늘 준비한 가이드가 여러분의 붉은 에러 창을 깨끗하게 지워주었기를 바랍니다. 막히는 부분이 있다면 언제든 댓글로 남겨주세요.
지금까지 데브프리였습니다. 감사합니다!
