Nginx 413 Request Entity Too Large 에러 원인 분석과 upload_max_filesize 완벽 해결법

대용량 파일 업로드 기능을 구현하고 서버에 테스트 파일인 10MB짜리 이미지를 전송했을 때 브라우저 화면에 '413 Request Entity Too Large' 에러가 발생하는 경험을 해봤을 것이다. 단순한 프론트엔드 유효성 검사 누락이나 파일 파싱 문제라고 생각하기 쉽다.
다만 Nginx 웹 서버와 PHP-FPM 애플리케이션 간의 업로드 용량 제한 설정 불일치가 원인이라는 사실을 모르는 경우가 많다.
이번에는 Nginx 413 에러가 정확히 무엇인지, 왜 발생하는지, 그리고 Nginx와 PHP 환경 설정을 통해 어떻게 해결하는지 완벽하게 정리해서 소개하겠다.

HTTP 413 Request Entity Too Large 상태 코드는 클라이언트가 서버로 보낸 HTTP 요청의 본문(Body) 용량이 서버에 설정된 최대 처리 한도를 초과할 때 발생한다. 주로 이미지, 동영상, PDF 문서 등 대용량 파일 업로드 요청을 처리할 때 마주친다.
웹 서비스 환경에서 요청은 브라우저 -> Nginx(웹 서버) -> PHP-FPM(애플리케이션) 순서로 전달된다. 이 중 어느 한 곳이라도 파일 크기 제한이 요청 크기보다 낮게 걸려 있으면 서버는 즉시 요청 처리를 중단하고 413 응답을 돌려준다.

요청 전달 흐름에 따른 각 서버 레이어별 제한 옵션과 기본값은 다음과 같다.

413 에러를 완벽하게 해결하려면 Nginx와 PHP 양쪽의 설정값을 모두 원하는 업로드 크기에 맞게 수정해야 한다. Nginx만 수정하고 PHP를 그대로 두면 '413' 대신 PHP 레벨의 파일 업로드 오류가 발생하며, 반대의 경우 Nginx에서 먼저 413 에러를 차단한다.

Nginx 설정 파일(/etc/nginx/nginx.conf 또는 /etc/nginx/conf.d/default.conf)을 열어 client_max_body_size 옵션을 추가하거나 수정한다. 이 옵션은 http, server, location 블록에 위치할 수 있다.

PHP 설정 파일(/etc/php/8.2/fpm/php.ini)에서 upload_max_filesize와 post_max_size를 수정한다. 이때 반드시 memory_limit > post_max_size >= upload_max_filesize 관계를 유지해야 안전하다.

다음은 50MB 용량의 파일 업로드를 허용하도록 Nginx와 PHP 설정을 적용하는 구체적인 예시 코드다.

✗ 잘못된 설정 (Nginx 설정을 누락하거나 PHP 설정 용량이 불균형한 경우)

# nginx.conf (client_max_body_size 미설정 시 기본값 1m 적용)
http {
    server {
        listen 80;
        server_name example.com;

        location /upload {
            # Nginx 제한을 풀지 않으면 PHP 설정과 관계없이 1MB 초과 시 413 에러 발생
            proxy_pass http://127.0.0.1:9000;
        }
    }
}

; php.ini
; post_max_size가 upload_max_filesize보다 작으면 대용량 파일 전송 실패
upload_max_filesize = 50M
post_max_size = 10M

✓ 올바른 설정 (Nginx와 PHP 설정을 상호 연동되도록 수치 맞춤)

# /etc/nginx/nginx.conf 또는 conf.d/vhost.conf
http {
    # 모든 가상 호스트에 일괄 적용 시 http 블록에 작성
    client_max_body_size 64M;

    server {
        listen 80;
        server_name example.com;

        location /api/upload {
            # 특정 업로드 경로만 지정하여 안전하게 제한 확장
            client_max_body_size 64M;
        }
    }
}

; /etc/php/8.2/fpm/php.ini
upload_max_filesize = 50M
post_max_size = 64M
memory_limit = 128M

설정을 마쳤다면 반드시 아래 bash 명령어로 설정 문법을 검사하고 프로세스를 재시작해야 변경 사항이 반영된다.

# Nginx 설정 문법 검사
sudo nginx -t

# Nginx 및 PHP-FPM 서비스 재시작
sudo systemctl restart nginx
sudo systemctl restart php8.2-fpm

결과 확인: 45MB 크기의 첨부파일 업로드 요청 시 413 에러 없이 정상적으로 HTTP 200 OK 응답이 수신된다.

✗ 잘못된 접근: post_max_size를 upload_max_filesize보다 작게 설정하는 실수다. POST 요청에는 파일 데이터 외에도 HTTP 헤더와 폼 필드 값이 포함되므로 post_max_size가 더 커야 한다.
✓ 올바른 접근: 용량 관계를 memory_limit(128M) > post_max_size(64M) >= upload_max_filesize(50M) 규격으로 여유 있게 설정한다.

✗ 잘못된 접근: 설정 파일 수정 후 nginx -t 및 systemctl restart 명령을 실행하지 않는 경우다. 메모리에 로드된 이전 Nginx 프로세스가 계속 구동 중이어서 동일한 413 에러가 반복된다.
✓ 올바른 접근: 설정 파일 변경 후에는 항상 Nginx 문법 검사를 수행하고 PHP-FPM 서비스와 함께 데몬을 재시작한다.

Nginx 413 Request Entity Too Large 에러 원인 분석과 upload_max_filesize 설정은 웹 서버와 애플리케이션 서버 간의 세심한 용량 설정 조율이 핵심이다. 개발 환경과 운영 환경의 서버 설정값을 동일하게 맞추는 습관이 모여서 안정적인 웹 서비스를 만든다는 점을 잊지 말자. 이 글의 Nginx 및 php.ini 설정 가이드를 참고해 파일 업로드 한도를 점검하고 재시작을 진행하면, 413 에러 없는 원활한 대용량 업로드 환경을 구축할 수 있을 것이다.