Nginx 기본 설정값인 client_max_body_size는 딱 1m로 잡혀 있습니다. 그래서 1MB를 살짝 넘는 이미지 파일 하나만 올려도 Nginx에서 413 Request Entity Too Large가 그대로 뜹니다. 결론부터 정리하면, 이 값은 http, server, location 세 곳 중 아무 데나 넣는다고 되는 게 아니라 업로드가 실제로 필요한 범위에 맞춰 넣어야 하고, 값도 무작정 키우기보다 실제 최대 업로드 용량보다 살짝 여유 있는 수준으로 맞추는 편이 안전합니다. 이 글은 Nginx 1.18 이상 최신 안정 버전대(1.24, 1.25 계열 포함)를 기준으로, 실제 설정 파일 예시와 함께 어디까지 확인해야 413이 완전히 사라지는지 정리했습니다.
client_max_body_size 기본값 1m가 413의 진짜 원인입니다
Nginx는 요청 본문(body) 크기가 client_max_body_size에 설정된 값을 넘으면 요청을 아예 처리하지 않고 곧바로 413 상태 코드를 응답합니다. 별도로 건드리지 않았다면 이 값은 1m, 즉 1메가바이트로 고정되어 있어서 사진 몇 장, 첨부파일 하나만 커도 바로 걸립니다.
버전에 따라 브라우저 화면에 뜨는 문구가 “Request Entity Too Large”가 아니라 “413 Payload Too Large”로 조금 다르게 보이는 경우도 있는데, 상태 코드 자체는 동일하게 413입니다. HTTP 상태 코드에서 413이 정확히 어떤 의미로 정의되어 있는지는 위키백과의 413 항목에서도 확인할 수 있듯, “요청 페이로드가 서버가 처리하려는 한도를 초과했다”는 뜻입니다. 즉 파일 자체가 손상됐거나 코드에 버그가 있어서가 아니라, Nginx가 정한 상한선에 걸린 것뿐입니다.
설정은 http, server, location 중 어디에 넣어야 하나요?
client_max_body_size는 세 곳 어디에나 넣을 수 있고, 더 좁은 범위의 설정이 넓은 범위의 설정을 덮어씁니다. 사이트 전체에 공통으로 적용할 기본값은 http 블록에, 업로드 페이지처럼 특정 경로에만 큰 용량을 허용하고 싶으면 location 블록에 따로 넣는 방식이 가장 안전합니다.
| 설정 위치 | 적용 범위 | 우선순위 |
|---|---|---|
| http | 서버 전체(모든 도메인)의 기본값 | 가장 낮음 |
| server | 해당 가상 서버(도메인) 전체 | 중간 |
| location | 지정한 경로(예: /upload)만 | 가장 높음 |
예를 들어 관리자 페이지의 파일 업로드 경로만 넉넉하게 열어주고 나머지 경로는 그대로 1m로 두고 싶다면, http에는 손대지 않고 해당 location 블록 안에만 값을 추가하면 됩니다. 반대로 http에 큰 값을 넣어버리면 사이트 전체 요청에 그 한도가 적용되니, 굳이 필요 없는 경로까지 위험 노출을 넓히게 됩니다.
실제 설정 예시와 적용 절차
워드프레스 미디어 업로드나 게시판 첨부파일처럼 일반적인 웹 서비스라면 아래 정도의 구성이 실무에서 흔히 쓰입니다.
http {
# 사이트 전체 기본값 (일반 폼 제출 등)
client_max_body_size 20m;
server {
server_name example.com;
location /upload {
# 업로드 전용 경로만 더 크게 허용
client_max_body_size 100m;
proxy_pass http://backend;
}
}
}설정 파일을 고친 뒤에는 반드시 문법 검사부터 해야 합니다.
sudo nginx -t
# 결과: syntax is ok / test is successful 이 나오면 정상
sudo nginx -s reload
# 또는 배포판에 따라
sudo systemctl reload nginxnginx -t를 건너뛰고 바로 reload했다가 설정 파일에 오타가 있으면 서비스가 죽는 경우가 있으니, 이 두 줄은 순서대로 실행하는 습관을 들이는 편이 낫습니다. client_max_body_size 지시어의 정확한 문법과 기본값은 client_max_body_size 공식 문서에 나와 있습니다.
0으로 풀어도 업로드가 다 되는 건 아닙니다 — 뒷단 제한이 따로 있습니다
client_max_body_size 0;으로 두면 Nginx 자체의 크기 검사는 꺼집니다. 다만 이건 트레이드오프가 있는 선택입니다. 검사를 꺼버리면 악의적인 대용량 요청이 그대로 뒷단까지 흘러가서 디스크나 메모리를 갉아먹을 수 있어서, 운영 서비스에서는 권장되지 않고 필요한 만큼만 숫자로 지정하는 편이 안전합니다.
또 하나 자주 놓치는 지점은, Nginx 설정을 아무리 늘려도 뒤에 있는 애플리케이션 서버 쪽 제한이 남아 있으면 413이나 비슷한 오류가 다시 뜬다는 점입니다. PHP-FPM을 쓰는 서버라면 php.ini의 upload_max_filesize와 post_max_size가 별도로 존재하고, Node.js 기반 서버라면 body-parser나 multer 같은 미들웨어에 설정된 크기 제한이 따로 적용됩니다. Nginx 앞단만 뚫고 이 부분을 안 건드리면 오류 메시지만 바뀌고 증상은 그대로인 경우가 많습니다.
413과 헷갈리는 414, 431도 구분해 두면 편합니다
413은 요청 본문(body) 크기 문제지만, 414(Request-URI Too Large)는 URL 자체가 너무 길 때, 431(Request Header Fields Too Large)은 쿠키나 헤더 값이 지나치게 클 때 발생합니다. 이 셋을 헷갈려서 client_max_body_size만 계속 키우다가 문제가 안 풀리는 경우가 종종 있습니다.
헤더나 쿠키 크기 문제라면 건드려야 할 지시어는 large_client_header_buffers입니다. 예를 들어 소셜 로그인 연동 후 쿠키가 커져서 431이 뜬다면 아래처럼 헤더 버퍼 쪽을 조정해야 하고, 이건 client_max_body_size와는 완전히 별개의 설정입니다.
http {
large_client_header_buffers 4 16k;
}증상이 413인지 431인지는 브라우저 개발자 도구의 네트워크 탭에서 응답 상태 코드를 직접 확인하는 게 가장 정확합니다.
설정을 바꾼 뒤에도 413이 남아있다면 이 순서로 확인해 보세요
client_max_body_size를 원하는 위치에 넣고 reload까지 했는데도 Nginx에서 413 Request Entity Too Large가 계속 뜬다면, 다음 순서로 짚어보는 편이 빠릅니다.
sites-enabled에 같은 도메인을 가리키는 설정 파일이 여러 개 있어서 다른 파일의 값이 실제로 적용되고 있는지 확인합니다.- 요청이 실제로 어떤
location블록을 타는지 확인하고, 그 블록 안에 값이 없으면 상위server나http값이 적용된다는 점을 다시 확인합니다. - 리버스 프록시 뒤에 있는 애플리케이션 서버(PHP-FPM, Node, Java 등)의 자체 업로드 제한값도 함께 올렸는지 확인합니다.
- 값을 올린 뒤 큰 파일을 업로드할 때 504(Gateway Timeout)가 새로 뜬다면
client_body_timeout,proxy_read_timeout같은 타임아웃 지시어도 같이 늘려야 합니다.
이 네 가지만 순서대로 확인하면 대부분의 413 문제는 원인이 잡힙니다. 다음 단계로는 현재 서버의 nginx.conf와 sites-available 파일을 열어 client_max_body_size가 몇 군데에 중복 설정되어 있는지부터 점검해 보시길 권합니다.
