웹 서비스를 운영하며 게시판이나 프로필 설정에 이미지나 첨부파일을 업로드할 때 "413 Request Entity Too Large" 에러 화면을 경험해본 적이 있을 것이다.
다만 대부분의 개발자들은 백엔드 프레임워크나 PHP 코드 문제로 오인하고 애플리케이션 설정만 변경하다가, 웹서버 계층에서 차단되는 원인을 찾지 못해 시간을 허비하곤 한다.
이번 글에서는 Nginx에서 발생하 413 Request Entity Too Large 에러의 정확한 원인과 왜 이 에러가 발생하는지, 그리고 Nginx와 백엔드 환경에서 대용량 파일 업로드 용량 제한을 안전하게 푸는 방법을 완벽하게 정리해서 소개하겠다.

HTTP 413 Status Code(Payload Too Large)는 클라이언트가 요청한 데이터(Payload)의 크기가 서버에서 처리할 수 있도록 허용된 기본 제한 용량을 초과했을 때 웹서버가 응답하는 오류다.
Nginx 웹서버는 기본적으로 요청 바디(Request Body)의 최대 크기를 제어하는 client_max_body_size 지시어(Directive)의 기본값이 1MB(1m)로 엄격하게 지정되어 있다.
따라서 사용자가 1MB가 넘는 사진, PDF, 압축 파일 등을 폼(Form) 전송이나 API 요청으로 보낼 경우, 요청이 백엔드 애플리케이션(PHP-FPM, Node.js, Python 등)에 도달하기도 전에 Nginx에서 즉각 413 에러를 반환하게 된다.

Nginx 설정 파일(nginx.conf 또는 conf.d/*.conf, sites-available/*) 내부에서 client_max_body_size 값을 변경하면 업로드 제한 용량을 조절할 수 있다.
이 설정은 적용하는 위치(Scope)에 따라 영향 범위가 달라진다.

실제 Nginx 설정 파일을 수정하여 업로드 용량을 30MB로 확장하는 방법과 백엔드(PHP) 연동 설정 방법을 살펴보자.

✗ 잘못된 코드 (Nginx 기본 설정 - 1MB 제한 상태로 운영):

server {
    listen 80;
    server_name example.com;

    # client_max_body_size 설정이 없거나 1m로 되어 있어 1MB 초과 시 413 에러 발생
    location /upload {
        fastcgi_pass php_backend;
    }
}

✓ 올바른 코드 (특정 server 또는 location 블록에 파일 제한 용량 변경):

server {
    listen 80;
    server_name example.com;

    # 해당 서버 전체의 업로드 허용 용량을 30MB로 지정
    client_max_body_size 30M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # 또는 대용량 파일 업로드가 이루어지는 특정 경로에만 50MB 적용 가능
    location /api/v1/files {
        client_max_body_size 50M;
        fastcgi_pass php_backend;
    }
}

Nginx 단에서 용량을 늘렸더라도, PHP-FPM을 사용 중이라면 php.ini의 설정값도 Nginx 제한 크기보다 크거나 같게 조정해야 한다.

✗ 잘못된 코드 (PHP 업로드 제한이 Nginx보다 작은 경우):

; Nginx는 30MB를 허용하지만 PHP가 2MB에서 차단함
upload_max_filesize = 2M
post_max_size = 8M

✓ 올바른 코드 (Nginx 설정에 맞추어 PHP 제한 값 동시 변경):

; 업로드할 개별 파일 최대 크기
upload_max_filesize = 30M

; POST 요청 전체 데이터 최대 크기 (upload_max_filesize보다 커야 함)
post_max_size = 35M

; 메모리 제한 및 실행 시간도 필요시 조정
memory_limit = 128M
max_execution_time = 300

설정 파일 변경 후 바로 Nginx를 재시작하면 구문 오류(Syntax Error)로 인해 서비스가 다운될 수 있다. 반드시 구문 검사 후 리로드해야 한다.

# 1. Nginx 문법 검사
$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

# 2. 문법 이상이 없을 경우 Nginx 설정 재적용 (무중단 reload)
$ sudo systemctl reload nginx

# 3. PHP-FPM 서비스 재시작 (PHP 설정을 변경한 경우)
$ sudo systemctl restart php7.4-fpm

출력 결과: nginx -t 결과에 syntax is ok 및 test is successful 메시지가 표시되면 무중단 리로드가 정상 완료된다.

Nginx 413 에러 처리 시 실무에서 흔히 범하는 세 가지 실수가 있다.

• 1) Nginx 설정만 변경하고 백엔드 설정을 잊는 경우: Nginx에서 30MB를 허용했더라도, PHP(php.ini)나 Node.js(express.json/urlencoded body limit)에서 용량 제한을 풀지 않으면 백엔드 애플리케이션 수준에서 2차 오류(500 에러 또는 파일 비어있음 문제)가 발생한다.
• 2) post_max_size 와 upload_max_filesize 관계 누락: PHP 환경에서는 반드시 post_max_size >= upload_max_filesize 관계가 성립해야 한다. 폼 전송 시 파일 데이터 외에도 기타 POST 파라미터가 포함되기 때문이다.
• 3) 무분별하게 너무 큰 용량(예: 2G 이상)을 허용하는 문제: 웹서버 전역(http 블록)에 client_max_body_size 0; (무제한)을 설정하면, 악의적인 사용자가 대용량 파일을 연속 전송하여 디스크 채우기 공격(DoS)을 시도할 때 서버가 마비될 위험이 있다. 필수 업로드 경로에만 적절한 용량을 부여하자.

Nginx 413 Request Entity Too Large 에러는 웹서버의 기본 안전장치가 정상 동작하고 있음을 의미한다. 무작정 제한을 풀기보다 실제 서비스에서 필요한 파일의 최대 용량을 산정한 뒤, Nginx의 client_max_body_size와 백엔드 환경설정을 균형 있게 맞춰주는 작은 최적화 습관이 서버의 안정성과 보안을 만드는 법이다. 이 글의 Nginx 및 PHP 설정 예제를 참고해 서비스 환경에 맞는 최적의 용량을 적용하면, 413 오류 없는 쾌적한 파일 업로드 환경을 구축할 수 있을 것이다.