Nginx 413 Request Entity Too Large 해결: 업로드 용량·프록시·Docker 점검

작은 파일은 올라가는데 큰 파일만 413 Request Entity Too Large로 실패한다면 요청 경로 어딘가의 본문 크기 제한을 넘은 것입니다. Nginx의 client_max_body_size가 대표 원인이지만 CDN, 로드밸런서, 두 번째 프록시, 애플리케이션 프레임워크에도 별도 제한이 있을 수 있습니다. 제한을 무작정 크게 만들기 전에 오류를 반환한 계층을 찾는 것이 먼저입니다.

1. 실패 파일 크기와 413을 반환한 계층을 확인한다

같은 형식의 작은 파일과 큰 파일을 각각 전송해 임계값을 좁히세요. 브라우저 개발자 도구의 응답 헤더, Nginx 접근·오류 로그, 애플리케이션 로그의 요청 도달 여부를 비교하면 어느 계층에서 차단됐는지 알 수 있습니다. 애플리케이션 로그에 요청이 없다면 앞단 프록시나 CDN을 먼저 봅니다.

증상우선 확인할 위치확인 방법

앱 로그에 요청이 없음	CDN·로드밸런서·Nginx	각 계층 접근 로그와 응답 헤더
Nginx 오류 로그에 too large	client_max_body_size	실제 적용 설정과 컨텍스트
Nginx는 전달, 앱이 413	프레임워크·업로드 미들웨어	애플리케이션 제한 설정
일정 시간 후 실패	본문 크기보다 타임아웃 가능성	상태 코드와 처리 시간 분리

413 오류는 Nginx 한 곳만 고치지 말고 CDN, 프록시, 애플리케이션의 업로드 제한을 요청 경로 순서대로 확인해야 합니다.

2. client_max_body_size의 실제 적용 위치를 찾는다

Nginx 공식 문서상 client_max_body_size 기본값은 1m이며 http, server, location 컨텍스트에 둘 수 있습니다. 더 구체적인 블록의 값이 적용되므로 다른 파일의 location /upload가 예상보다 작은 제한을 가질 수 있습니다. nginx -T로 include된 파일까지 펼친 최종 설정을 확인하세요.

nginx -T | grep -n client_max_body_size

server {
    client_max_body_size 100m;
    location /upload/ {
        proxy_pass http://app:8080;
    }
}

0은 크기 검사를 끄지만 업로드 남용과 디스크·메모리 고갈 위험이 커질 수 있습니다. 서비스가 실제 허용할 최대치보다 조금 큰 명시적 제한을 권장합니다.

3. 설정 문법 검사 후 재로드한다

설정 파일을 수정한 뒤 바로 컨테이너를 재시작하기보다 문법 검사를 먼저 실행하세요. 검사가 성공하면 reload로 기존 연결 영향을 줄일 수 있습니다. 오류가 나면 파일 경로와 중복 지시어를 고친 뒤 다시 검사합니다.

nginx -t
nginx -s reload

4. Docker에서는 수정한 파일이 실행 컨테이너에 반영됐는지 본다

호스트의 설정을 고쳤지만 컨테이너에 다른 파일이 마운트됐거나 이미지 내부 기본 설정을 쓰는 경우가 많습니다. 컨테이너 안에서 nginx -T를 실행해 실제 값을 확인하세요. Compose의 볼륨 경로, 읽기 전용 옵션, 재생성 여부도 함께 봅니다.

docker compose exec nginx nginx -T
docker compose exec nginx nginx -t
docker compose exec nginx nginx -s reload

5. 애플리케이션과 CDN 제한도 같은 값으로 정렬한다

Node, Spring, PHP, Django 같은 프레임워크나 업로드 라이브러리는 자체 본문·멀티파트 제한을 둘 수 있습니다. 앞단 Nginx를 100MB로 열어도 앱이 10MB만 허용하면 다시 실패합니다. CDN과 로드밸런서는 변경 불가능한 최대 한도가 있을 수 있으므로 공식 사양을 확인하고, 대용량 파일은 객체 스토리지의 사전 서명 URL로 직접 업로드하는 구조도 검토하세요.

6. 운영 점검 체크리스트

1. 실패 파일의 실제 바이트 크기와 응답 상태를 기록합니다.
2. 요청이 CDN, 로드밸런서, Nginx, 앱 중 어디까지 도달했는지 확인합니다.
3. nginx -T로 최종 적용된 컨텍스트와 값을 찾습니다.
4. 서비스 요구보다 조금 큰 제한을 설정하고 nginx -t를 통과시킵니다.
5. 프레임워크·멀티파트·객체 스토리지 제한을 같은 기준으로 맞춥니다.
6. 허용 크기 바로 아래와 위 파일로 성공·실패 경계를 시험합니다.
7. 인증, 파일 형식 검사, 저장 용량 모니터링을 함께 적용합니다.

413이 아니라 프록시 연결 실패로 502가 보인다면 Nginx 502 Bad Gateway와 Docker upstream 점검법을 참고하세요.

7. 자주 묻는 질문

Q. client_max_body_size를 0으로 두면 해결되나요?
크기 검사를 끌 수 있지만 무제한 업로드 위험이 생깁니다. 업무상 최대치를 정하고 명시적으로 제한하는 편이 안전합니다.

Q. 설정을 바꿨는데 계속 413이 납니다.
다른 server/location 블록, 컨테이너 내부 설정, CDN 또는 애플리케이션 제한이 적용되는지 확인하세요.

Q. 큰 파일은 항상 Nginx를 거쳐야 하나요?
객체 스토리지의 사전 서명 URL을 사용해 브라우저가 직접 업로드하고 앱은 권한과 메타데이터만 관리하는 방식도 가능합니다.

공식 자료: Nginx client_max_body_size · Nginx 명령행 매개변수와 설정 검사 · Nginx reload 절차 (확인일: 2026-09-23)