llm-wiki/raw/official-docs/nginx-client-max-body-size.md

---
title: "nginx — client_max_body_size Directive (ngx_http_core_module)"
source_type: official-doc
url: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size
archive_url:
status: raw
confidence: high
tags: [nginx, gateway, file-upload, size-limit, http]
related_projects: []
related_branches: [feature-file-resource-handling-contract]
created: 2026-05-27
last_reviewed: 2026-05-27
---

# nginx — client_max_body_size Directive (ngx_http_core_module)

> Layer: `raw/official-docs/` — nginx 공식 reference 문서의 `client_max_body_size` directive 원문 발췌. ca-tmpl 의 gateway-level 파일 크기 제한 메커니즘의 근거.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-file-resource-handling-contract]] | D4 gateway-level 파일 크기 제한 메커니즘 — nginx `client_max_body_size` 가 limit 초과 시 HTTP 413 응답을 반환하며, default 는 1m, 컨텍스트는 `http`/`server`/`location` |

## 컨텍스트

ca-tmpl `feature-file-resource-handling-contract` 의 D4 는 application layer (Spring Boot multipart limit) 이전에 gateway (nginx) 에서 1차 size 차단을 둔다는 결정. 본 source 는 nginx `client_max_body_size` directive 의 공식 spec — syntax / default / context / 초과 시 동작 (HTTP 413).

## 출처 / Source

- 원본 URL: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size
- 아카이브 URL: (미수집)
- 저자 / 조직: nginx, Inc. / F5 (공식 nginx project)
- 발행일: rolling docs
- 마지막 확인일: 2026-05-27

## 왜 저장했는지 / Why archived

ca-tmpl 의 파일 업로드 흐름이 (a) 게이트웨이 nginx 에서 1차 size 검증, (b) 앱 Spring multipart 에서 2차 검증, (c) S3 / object storage 가 3차 검증으로 다층 방어함을 정당화. 1차 방어선의 directive 가 정확히 어떤 응답을 반환하는지 (HTTP 413) 의 공식 verbatim 이 핵심.

## 핵심 인용 / Key quotes (verbatim)

> [§client_max_body_size] "Syntax: **client_max_body_size** `size`;"

> [§client_max_body_size] "Default: client_max_body_size 1m;"

> [§client_max_body_size] "Context: `http`, `server`, `location`"

> [§client_max_body_size] "Sets the maximum allowed size of the client request body. If the size in a request exceeds the configured value, the 413 (Request Entity Too Large) error is returned to the client."

> [§client_max_body_size] "Please be aware that browsers cannot correctly display this error."

> [§client_max_body_size] "Setting `size` to 0 disables checking of client request body size."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| NGINX-CMB-C1 | `client_max_body_size` directive 의 syntax 는 `client_max_body_size size;` | [§client_max_body_size] "Syntax: **client_max_body_size** `size`;" | `official-vendor-doc` | 모든 nginx 설정 | `size` 의 단위 (k/m/g) 와 정수 표현 규칙은 본 인용 범위 밖 (nginx 공통 size 표기) |
| NGINX-CMB-C2 | `client_max_body_size` 의 default 값은 `1m` (1 megabyte) | [§client_max_body_size] "Default: client_max_body_size 1m;" | `official-vendor-doc` | nginx 의 모든 설정 컨텍스트 (명시적 override 없는 경우) | 1m 가 모든 배포에서 충분하다는 뜻은 아님 — 단지 nginx 의 default 값일 뿐 |
| NGINX-CMB-C3 | `client_max_body_size` 는 `http`, `server`, `location` 세 컨텍스트에서 설정 가능 | [§client_max_body_size] "Context: `http`, `server`, `location`" | `official-vendor-doc` | nginx 설정의 scope override 패턴 | upstream / map / if 컨텍스트에서는 사용 불가 (본 인용 범위 밖, 추론) |
| NGINX-CMB-C4 | request body size 가 설정값을 초과하면 nginx 는 HTTP 413 (Request Entity Too Large) 응답을 client 에 반환 | [§client_max_body_size] "Sets the maximum allowed size of the client request body. If the size in a request exceeds the configured value, the 413 (Request Entity Too Large) error is returned to the client." | `official-vendor-doc` | client → nginx 의 request body 크기 검증 | "request body size" 가 Content-Length 헤더 기반인지, 실제 수신 byte 누적 기반인지는 본 인용 범위 밖 (실제로는 둘 다 검증) |
| NGINX-CMB-C5 | 413 응답이 일부 브라우저에서 정확히 표시되지 않을 수 있음 (UX 한계 경고) | [§client_max_body_size] "Please be aware that browsers cannot correctly display this error." | `official-vendor-doc` | UX 측면의 413 응답 처리 | 어떤 브라우저가 어떻게 처리하는지의 detail 은 본 인용 범위 밖 |
| NGINX-CMB-C6 | `client_max_body_size` 를 `0` 으로 설정하면 request body size 검사 자체가 비활성화 | [§client_max_body_size] "Setting `size` to 0 disables checking of client request body size." | `official-vendor-doc` | size 검사를 의도적으로 끌 때 (예: streaming proxy, large upload endpoint) | "검사 비활성화" 가 upstream / 후속 module 에서 size 검사가 일어나지 **않는다** 는 뜻은 아님 — nginx core 단의 check 만 비활성 |

### Strength

모두 `official-vendor-doc` (nginx 공식 reference module 문서).

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `NGINX-CMB-C1` ~ `C3`: directive 의 syntax / default / context 정의
  - `NGINX-CMB-C4`: 초과 시 HTTP 413 응답 반환 (= gateway-level 1차 차단의 mechanic)
  - `NGINX-CMB-C5`: 413 응답의 브라우저 표시 한계 (UX 경고)
  - `NGINX-CMB-C6`: 0 설정으로 검사 비활성화 가능
- **이 자료가 증명하지 않는 것**:
  - nginx 가 Content-Length 헤더와 실제 수신 byte 중 어느 것으로 size 를 판정하는지 — 본 인용은 "the size in a request" 로 일반화
  - chunked transfer encoding 에서의 동작 (Content-Length 없음)
  - 413 응답의 정확한 status line / body / 헤더 형식
  - nginx 가 size 초과를 감지하는 시점 (header 단계 vs body 수신 도중)
  - `client_body_buffer_size`, `client_body_temp_path` 등 관련 directive 와의 상호작용
- **내 프로젝트 (ca-tmpl) 에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl 의 nginx (또는 다른 gateway) 가 `client_max_body_size` 의 default 1m 를 그대로 두는지, 명시적 override 하는지 확인
  - nginx 의 413 응답이 ca-tmpl 앱의 error 응답 포맷 (예: JSON `{"error": ...}`) 과 일치하는지 — 일반적으로 nginx default 413 은 HTML 이므로 별도 `error_page` 또는 custom response 필요
  - ca-tmpl 의 Spring Boot multipart limit (`spring.servlet.multipart.max-file-size` / `max-request-size`) 와 nginx limit 의 정합성 — 일반적으로 gateway limit ≥ app limit (gateway 가 먼저 차단)
  - ca-tmpl 의 upload endpoint 가 streaming 인 경우 `0` 으로 nginx 검사 비활성 후 app 단 검증으로 위임할지 결정

## 메모 / Notes

- 본 capture 는 nginx core module 의 `client_max_body_size` 만 다룸 — 관련 directive (`client_body_buffer_size`, `client_body_timeout`) 는 별도 capture 필요 시.
- 다음 후보 fetch:
  - https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size — buffering 동작
  - Spring Boot 의 `spring.servlet.multipart.max-file-size` 공식 reference — app layer 와의 정합성 검증

## Related / 관련

- 같은 주제 다른 official-doc / company-tech-blog: (없음 — Spring multipart limit 의 official-doc 미수집)
- 인용하는 branch:
  - [[raw/branch-notes/feature-file-resource-handling-contract]]
- 인용하는 project:
  - [[raw/project-notes/ca-skeleton-operational-contract]]
- 인용한 wiki 요약: (미작성)