대용량 파일 업로드 기능을 개발하고 로컬 환경에서 테스트를 마친 뒤 운영 서버에 배포했을 때 413 Request Entity Too Large 에러를 경험해봤을 것이다.
작은 이미지 파일은 정상적으로 잘 올라가는데, 10MB나 50MB가 넘는 동영상이나 압축 파일을 올리는 순간 브라우저 화면에 413 상태 코드가 찍히며 요청이 차단된다.
다만 대부분의 개발자들은 이 에러가 발생하는 정확한 레이어 위치와 웹 서버-백엔드 간의 설정 연동 구조를 모른 채 무작정 구글링한 설정값만 복사해 붙인다.
이번에는 Nginx 413 에러가 왜 발생하는지 원인을 명확히 파악하고, client_max_body_size 설정법과 PHP 등 백엔드 엔진의 제한 용량을 올바르게 동기화하는 방법을 완벽하게 정리해서 소개하겠다.
HTTP 413 Request Entity Too Large 에러는 클라이언트가 전송한 HTTP 요청 본문(Body)의 크기가 웹 서버가 허용하도록 설정된 최대 제한 용량을 초과했을 때 웹 서버가 거부 응답을 반환하는 현상이다.
파일 업로드 시 클라이언트는 HTTP POST 요청의 Multi-part Form Data 형태로 데이터를 쪼개어 전송한다. 이때 Nginx는 백엔드 애플리케이션(PHP-FPM, Node.js, Spring Boot 등)으로 요청을 넘기기 전에 전면에서 요청 본문의 크기를 먼저 검사한다.
Nginx의 본문 용량 제한 지시어인 client_max_body_size의 기본 설정값은 1MB(1m)다. 따라서 별도의 설정을 추가하지 않은 기본 Nginx 서버에서는 1MB를 초과하는 그 어떤 파일 업로드 요청도 백엔드 코드에 도달하기 전에 Nginx 래퍼 수준에서 차단당한다.
파일 업로드가 정상적으로 처리되려면 클라이언트 요청이 거치는 모든 관문(Nginx 웹 서버 -> 백엔드 언어 런타임 -> 프레임워크 및 데이터베이스)의 용량 제한이 순차적으로 확보되어야 한다.
| 레이어 | 설정 위치 | 설정 항목 | 기본값 | 역할 및 특징 |
|---|---|---|---|---|
| Nginx 웹 서버 | nginx.conf / site.conf | client_max_body_size | 1m | HTTP 요청 본문(Body)의 수신 최대 크기 제한 |
| PHP 백엔드 | php.ini | upload_max_filesize | 2M | 업로드되는 단일 파일 하나의 최대 크기 |
| PHP 백엔드 | php.ini | post_max_size | 8M | POST 요청 전체 본문 데이터의 최대 크기 |
Nginx에서 파일 업로드 용량을 확장하기 위해서는 client_max_body_size 지시어를 적절한 위치에 추가해야 한다.
이 지시어는 http, server, location 블록에 각각 선언할 수 있어 사이트 전체 또는 특정 파일 업로드 API 경로에만 선택적으로 대용량 허용 방침을 적용하는 것이 가능하다.
1) http 블록: Nginx 서버 내의 모든 가상 호스트(웹사이트) 전체에 일괄 적용된다.
2) server block: 특정 도메인(가상 호스트) 단위로 용량을 제한할 때 사용한다.
3) location block: /api/upload 같은 특정 엔드포인트 URL 경로에만 대용량 허용을 적용할 때 가장 효율적이다.
Nginx 설정만 변경한다고 해서 문제가 완전히 해결되지 않는다. 백엔드가 PHP인 경우 php.ini의 post_max_size와 upload_max_filesize도 Nginx 설정 이상으로 올려주어야 한다.
✗ 잘못된 설정 (용량 지시어 누락으로 기본값 1M 적용)
http {
include /etc/nginx/mime.types;
default_type application/octet-stream;
server {
listen 80;
server_name example.com;
location /upload {
fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
include fastcgi_params;
}
}
}✓ 올바른 설정 (50MB 업로드를 허용하도록 location 블록에 설정 추가)
http {
include /etc/nginx/mime.types;
default_type application/octet-stream;
# 전역 기본값 설정 (필요시)
client_max_body_size 10M;
server {
listen 80;
server_name example.com;
# 일반 경로
location / {
try_files $uri $uri/ /index.php?$query_string;
}
# 대용량 파일 업로드 전용 API 경로
location /api/v1/upload {
# 해당 경로만 50MB로 확장 허용
client_max_body_size 50M;
fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root/index.php;
include fastcgi_params;
}
}
}
Nginx에서 50MB를 허용했더라도 PHP의 설정이 50MB 미만이면 PHP 레벨에서 파일이 잘리거나 Warning이 발생하며 $_FILES 배열이 비어버린다. 따라서 아래와 같이 삼박자를 맞춰주어야 한다.
✗ 잘못된 php.ini 설정 (post_max_size가 upload_max_filesize보다 작거나 Nginx 용량보다 작은 경우)
upload_max_filesize = 50M
post_max_size = 8M
memory_limit = 128M✓ 올바른 php.ini 설정 (memory_limit >= post_max_size >= upload_max_filesize 관계 성립)
upload_max_filesize = 50M
post_max_size = 55M
memory_limit = 256M
설정 파일 변경 후에는 반드시 Nginx 구문 검사를 진행하고 프로세스를 재로드해야 설정이 반영된다.
# 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
# Nginx 및 PHP-FPM 서비스 데몬 재로드
$ sudo systemctl reload nginx
$ sudo systemctl reload php8.2-fpm
✗ Nginx만 수정하고 백엔드 설정을 잊는 경우
Nginx의 client_max_body_size를 100M로 올렸지만 백엔드(Node.js의 body-parser, Spring의 max-file-size, PHP의 php.ini 등) 설정을 건드리지 않으면 Nginx는 통과하지만 백엔드 앱에서 400 Bad Request 또는 파일 유실 오류가 발생한다.
✗ Cloudflare 등 CDN 프록시의 기본 제한값 간과
Nginx와 백엔드 서버의 설정을 아무리 1GB로 올려두어도, 서버 전면에 Cloudflare 무료 플랜을 사용하고 있다면 Cloudflare 자체가 100MB를 초과하는 요청을 413 Payload Too Large로 차단한다. CDN 전면 프록시를 사용할 경우 해당 서비스의 요금제별 업로드 제한 용량을 반드시 확인해야 한다.
✗ client_max_body_size 0 설정의 위험성
0으로 설정하면 본문 크기 제한을 완전히 비활성화할 수 있다. 하지만 이를 전역(http 블록)으로 설정해두면 악의적인 사용자가 무제한 용량의 요청을 지속해서 보내 서버 메모리와 디스크 공간을 고갈시키는 디도스(DDoS) 공격 표적이 될 수 있다. 제한 해제는 반드시 업로드가 일어나는 특정 location 블록에만 명시하는 것이 안전하다.
Nginx 413 Request Entity Too Large 에러는 대용량 파일 업로드를 다루는 백엔드 환경에서 반드시 통과해야 하는 관문이다. 웹 서버와 애플리케이션 레이어 간의 용량 정책을 일치시키는 작은 습관이 모여서 안정적인 파일 전송 환경이라는 큰 효과를 만든다는 점을 잊지 말자. 이 글의 Nginx 및 백엔드 설정 체크리스트를 참고해 가상 호스트 파일을 수정하고 서버를 재로드하면, 413 에러 없는 쾌적한 업로드 서비스를 구축할 수 있을 것이다.