오류 증상
프론트 (Next.js) 에서 API 로 첨부파일 이미지 업로드를 하려고 하는데 아래와 같이 에러 메시지 발생
네트워크 오류: Failed to fetch
로컬에서는 됐는데 운영에 반영 후 발생
의심 원인
-> 클라이언트 코드는 fetch(POST FormData) 단순 호출이고, "Failed to fetch"는 fetch가 응답을 받기 전에 네트워크 레벨에서 끊겼다는 신호입니다. 200 OK 못 받은 게 아니라 연결 자체가 안 됐다는 뜻이라, 백엔드 코드 문제라기보단 인프라/네트워크 레벨일 가능성이 높습니다.
1순위 : nginx client_max_body_size 초과 (가장 유력)
현재 클라이언트 검증은 5MB까지 허용해 놓은 상태이지만 nginx의 client_max_body_size 기본값은 1MB 이므로
명시적으로 안 올렸으면 1MB 초과 요청이 들어오면 연결을 그냥 끊거나 413으로 응답하는데,
일부 케이스에서 클라가 "Failed to fetch"로 받음 (특히 nginx가 헤더 다 받기 전에 연결 종료할 때)
🐰 확인 방법 1 (서버에서):
(Docker nginx)
docker compose exec nginx grep -rn "client_max_body_size" /etc/nginx
또는
(직접 설치 nginx)
grep -rn "client_max_body_size" /etc/nginx/ 2>/dev/null
-> 결과가 비어있거나 1m로 작게 잡혀있으면 거의 확정
🐰 확인 방법 2:
50KB 정도 아주 작은 이미지(스크린샷 등)로 업로드 -> 성공하면 1순위 확정
🐰 해결 방법:
서버 nginx 설정에 추가
(Docker nginx)
nano ~/app/nginx/default.conf
또는
(직접 설치 nginx)
nano /etc/nginx/conf.d/default.conf 또는 nano /etc/nginx/sites-available/
API server 블록에 client_max_body_size 추가
server {
listen 443 ssl;
server_name api.venny.com;
client_max_body_size 5M;
...
저장 후 nginx 문법검사 -> reload 적용
(Docker nginx)
docker compose exec nginx nginx -t
docker compose exec nginx nginx -s reload
또는
(직접 설치 nginx)
sudo nginx -t
sudo nginx -s reload
해결 완료!
참고로,
nginx에서 막히면:
HTTP 413 에러 Request Entity Too Large 메시지 Spring Boot까지 요청이 안 감
Spring Boot에서 막히면:
HTTP 500 에러 MaxUploadSizeExceededException 예외 발생 로그에 the request was rejected because its size exceeds the configured maximum 출력
-> 이때는 application.yml 파일 설정 확인 필요
spring:
servlet:
multipart:
max-file-size: 5MB
max-request-size: 5MB
만약 위의 방법으로 해결을 못했다면 아래 내용 참고
2순위 : ⭐ 모바일 셀룰러 네트워크의 timeout / 끊김
- 모바일 데이터망에서 multipart 업로드는 PC Wi-Fi보다 훨씬 자주 끊김
- 큰 파일이면 더 잦음
- 확인: 모바일에서 Wi-Fi로 전환해 다시 시도. Wi-Fi에선 되면 셀룰러 네트워크 + 큰 파일 조합 문제.
3순위 : 광고차단·VPN·콘텐츠 필터링 앱
- 모바일에 설치된 광고 차단(예: 1Blocker, AdGuard), VPN, 또는 통신사 콘텐츠 필터가 api 도메인을 차단할 수 있음
- 일반 GET API는 통과하는데 POST multipart만 막는 필터도 가끔 있음
- 확인: VPN/광고차단 끄고 시도, 또는 사파리/크롬 등 다른 브라우저로 시도.
4순위 : (가능성 낮음) iOS Safari의 HTTPS 인증서 / 인증 체인 엄격성
- iOS는 인증서 intermediate chain 누락에 매우 엄격
- 그러나 GET이 잘 된다면 인증서 자체는 문제 없음
- 확인: 모바일 사파리에서 api 웹 사이트에 직접 접속 → 인증서 경고 뜨지 않으면 4순위 제외