[태그:] Nginx 413 오류

Nginx 웹서버에서 이미지나 동영상, 압축파일을 업로드하려는데 갑자기 413 Request Entity Too Large 오류가 발생하는 경우가 있습니다. 작은 파일은 정상적으로 업로드되지만 특정 크기 이상의 파일만 실패하거나, API 요청을 보낼 때 413 상태 코드가 반환되는 현상도 나타날 수 있습니다.

이런 오류가 발생하면 서버 저장 공간이 부족하거나 파일 권한에 문제가 있다고 생각하기 쉽습니다. 하지만 413 오류는 대부분 클라이언트가 전송한 HTTP 요청 본문(Request Body)의 크기가 서버 또는 중간 프록시에서 허용한 제한을 초과했을 때 발생합니다.

특히 Nginx의 client_max_body_size 설정이 실제 업로드 크기보다 작거나, Nginx 앞단의 CDN·로드밸런서, 뒷단의 PHP·애플리케이션 서버가 별도의 용량 제한을 적용하고 있다면 설정을 한 곳만 변경해도 문제가 계속될 수 있습니다.

이번 글에서는 413 오류 발생 위치 확인 → Nginx 업로드 제한 점검 → client_max_body_size 변경 → PHP 및 프록시 제한 확인 → 설정 검증 순서로 안전하게 해결하는 방법을 살펴봅니다.

413 Request Entity Too Large 핵심 명령어 한눈에 보기

413 오류가 발생했다면 아래 명령어로 Nginx 설정과 오류 로그를 먼저 확인할 수 있습니다.

PHP CLI에서 조회한 설정과 실제 PHP-FPM 웹 요청에 적용되는 설정은 다를 수 있습니다. 따라서 PHP를 사용하는 환경에서는 웹 요청을 처리하는 PHP-FPM의 설정도 별도로 확인해야 합니다.

1. Nginx 413 오류가 발생하는 원인

HTTP 413은 요청 본문의 크기가 서버에서 처리하도록 허용한 크기를 초과했다는 의미입니다. 현재 HTTP 표준에서는 413 Content Too Large라는 명칭을 사용하지만, Nginx 오류 페이지나 기존 문서에서는 413 Request Entity Too Large라는 표현도 널리 사용됩니다.

대표적인 발생 원인은 다음과 같습니다.

• Nginx 업로드 제한: client_max_body_size보다 큰 요청을 전송한 경우
• PHP 제한: upload_max_filesize 또는 post_max_size가 부족한 경우
• 애플리케이션 제한: Node.js, Django 등에서 요청 본문 크기를 제한한 경우
• 프록시 제한: CDN, API Gateway 또는 로드밸런서에서 요청을 차단한 경우
• 요청 크기 증가: 파일 외에 multipart 데이터나 JSON 본문이 추가된 경우
• 설정 적용 오류: 다른 server 또는 location 블록의 설정이 적용되는 경우

중요한 점은 413 오류가 반드시 Nginx 자체에서 생성된 것은 아니라는 사실입니다. 중간 프록시나 애플리케이션 서버가 413을 반환할 수도 있으므로 어느 계층에서 제한이 발생했는지 구분해야 합니다.

2. 오류 로그에서 요청 크기 초과 여부 확인하기

Nginx가 요청 본문을 차단했다면 오류 로그에 관련 메시지가 기록될 수 있습니다.

sudo tail -n 100 /var/log/nginx/error.log

대표적인 메시지는 다음과 같습니다.

client intended to send too large body: 12582912 bytes

위 예시는 클라이언트가 약 12MiB 크기의 요청 본문을 전송하려 했다는 의미입니다. 설정된 허용 크기보다 요청 본문이 크면 Nginx가 413 응답을 반환할 수 있습니다.

다만 로그 파일의 위치는 배포판과 Nginx 설정에 따라 다르며, 로그 레벨이나 요청 처리 경로에 따라 같은 메시지가 남지 않을 수도 있습니다.

따라서 Nginx 로그에 관련 기록이 없다면 앞단 프록시와 뒷단 애플리케이션 로그도 확인해야 합니다.

3. client_max_body_size 설정 확인하기

Nginx에서 HTTP 요청 본문의 최대 허용 크기를 제어하는 대표적인 지시어는 client_max_body_size입니다.

Nginx의 기본값은 일반적으로 1m이며, 설정 파일에서 명시적으로 변경할 수 있습니다.

sudo nginx -T 2>&1 | grep -n client_max_body_size

이 명령어는 Nginx가 읽는 설정 파일들을 출력한 뒤 해당 지시어가 포함된 줄을 검색합니다.

다만 검색 결과만으로 어떤 server 또는 location 블록에 설정이 적용되는지 확정할 수는 없습니다. 실제 요청을 처리하는 가상 호스트와 경로의 설정 구조를 확인해야 합니다.

client_max_body_size는 http, server, location 컨텍스트에 지정할 수 있습니다. 하위 컨텍스트에서 별도로 설정하면 해당 범위의 값이 적용됩니다.

4. Nginx 업로드 용량 제한 변경하기

예를 들어 최대 50MiB의 요청 본문을 허용하려면 해당 사이트의 server 블록에 다음 설정을 추가할 수 있습니다.

server {
    listen 80;
    server_name example.com;

    client_max_body_size 50m;

    # 기존 사이트 설정
}

특정 업로드 경로에만 제한을 적용하려면 해당 location 블록에 설정할 수도 있습니다.

location /upload/ {
    client_max_body_size 50m;

    proxy_pass http://127.0.0.1:3000;
}

위 코드는 프록시를 사용하는 환경의 예시입니다. 실제 사이트에 이미 location 블록이 있다면 새 블록을 무작정 추가하지 말고 기존 요청 처리 설정에 맞춰 수정해야 합니다.

또한 50m은 요청 본문 전체에 적용되는 제한입니다. multipart/form-data 업로드에서는 파일 내용 외에도 폼 필드와 구분자 등의 데이터가 포함되므로 파일 크기와 요청 본문 크기가 정확히 일치하지 않을 수 있습니다.

따라서 최대 50MiB 파일을 허용하려는 목적이라면 실제 요청 본문 크기를 고려해 적절한 여유를 두는 것이 좋습니다.

5. 설정을 수정했는데 413 오류가 계속 발생하는 경우

client_max_body_size를 늘렸는데도 오류가 계속된다면 설정이 실제로 적용됐는지 먼저 확인해야 합니다.

sudo nginx -t

정상적인 경우 다음과 비슷한 결과가 표시됩니다.

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

설정 문법이 정상이라면 변경 사항을 다시 불러옵니다.

sudo systemctl reload nginx

이후 실제 적용된 설정을 확인합니다.

sudo nginx -T

다음 항목도 함께 점검해야 합니다.

• 설정을 수정한 파일이 실제 Nginx에서 로드되는지
• 요청 도메인이 올바른 server 블록과 일치하는지
• 요청 경로에 다른 location 설정이 적용되는지
• Docker 컨테이너 내부의 Nginx를 별도로 사용하고 있는지
• CDN 또는 리버스 프록시가 앞단에서 요청을 제한하는지

특히 여러 개의 Nginx 인스턴스나 프록시를 운영하는 환경에서는 한 서버의 설정만 변경해도 실제 요청이 다른 서버를 거칠 수 있습니다.

6. PHP 업로드 제한도 함께 확인하기

워드프레스처럼 PHP를 사용하는 웹사이트라면 Nginx 제한 외에도 PHP 업로드 설정을 확인해야 합니다.

PHP 설정에서 주로 확인하는 항목은 다음과 같습니다.

upload_max_filesize = 50M
post_max_size = 60M

upload_max_filesize는 개별 업로드 파일의 크기 제한이며, post_max_size는 POST 요청 데이터 전체의 크기 제한입니다.

따라서 일반적으로 post_max_size는 upload_max_filesize보다 충분히 크게 설정해야 합니다. 여러 파일을 한 번에 업로드한다면 전체 요청 크기도 고려해야 합니다.

또한 PHP의 memory_limit와 애플리케이션의 파일 처리 방식에 따라 별도의 메모리 문제가 발생할 수 있지만, 메모리 제한이 곧바로 Nginx의 413 오류를 의미하는 것은 아닙니다.

PHP-FPM 설정을 수정했다면 해당 서비스의 설정을 검증하고 실제 PHP-FPM 서비스에 변경 사항을 반영해야 합니다. 서비스 이름은 설치된 PHP 버전에 따라 다릅니다.

7. Node.js와 API 서버에서 발생하는 413 오류

Nginx가 Node.js 애플리케이션으로 요청을 전달하는 구조에서는 Nginx 제한을 늘려도 애플리케이션에서 별도의 요청 크기 제한이 적용될 수 있습니다.

예를 들어 Express의 JSON 요청 본문 파서는 다음과 같이 크기 제한을 설정할 수 있습니다.

app.use(express.json({ limit: '10mb' }));

이 경우 Nginx에서 50MiB를 허용하더라도 JSON 본문이 애플리케이션의 10MB 제한을 초과하면 요청이 거부될 수 있습니다.

다만 JSON 본문 제한과 multipart 파일 업로드 제한은 서로 다른 미들웨어에서 처리될 수 있으므로 구분해야 합니다.

실제 413 응답이 Nginx에서 생성된 것인지 애플리케이션에서 생성된 것인지 로그와 응답 내용을 비교하는 것이 중요합니다.

8. client_max_body_size를 무제한으로 설정해도 될까?

Nginx에서는 다음과 같이 설정할 수 있습니다.

client_max_body_size 0;

이 값은 Nginx의 요청 본문 크기 검사를 비활성화합니다. 하지만 무제한 업로드를 허용하면 서버 자원 사용량과 악의적인 대용량 요청에 대한 위험이 커질 수 있습니다.

따라서 운영 환경에서는 가능한 한 서비스에 필요한 업로드 크기를 기준으로 적절한 상한을 설정하는 것이 좋습니다.

또한 업로드 제한을 높일 때는 디스크 용량, 임시 파일 저장 경로, 업로드 처리 시간, 애플리케이션 검증 및 접근 제어도 함께 고려해야 합니다.

실전 점검 순서

Nginx에서 413 Request Entity Too Large 오류가 발생했다면 다음 순서로 점검할 수 있습니다.

# 1. Nginx 오류 로그 확인
sudo tail -n 100 /var/log/nginx/error.log

# 2. 현재 업로드 제한 설정 검색
sudo nginx -T 2>&1 | grep -n client_max_body_size

# 3. 실제 가상 호스트와 location 설정 확인
sudo nginx -T

# 4. 설정 수정 후 문법 검사
sudo nginx -t

# 5. 정상일 때 설정 다시 불러오기
sudo systemctl reload nginx

# 6. PHP 사용 환경의 제한 확인
php -i | grep -E 'upload_max_filesize|post_max_size'

# 7. 오류 로그 재확인
sudo tail -n 100 /var/log/nginx/error.log

PHP CLI의 설정 조회는 참고용이며, PHP-FPM을 사용하는 경우에는 실제 웹 요청에 적용되는 설정을 별도로 확인해야 합니다.

설정 변경 후에는 기존에 실패했던 파일과 허용 크기보다 큰 테스트 파일을 각각 업로드해 제한이 의도한 대로 동작하는지 확인하는 것이 좋습니다.

정리

Nginx에서 413 Request Entity Too Large 오류가 발생하는 가장 대표적인 이유는 요청 본문의 크기가 서버에서 허용한 제한을 초과했기 때문입니다.

Nginx가 요청을 차단했다면 client_max_body_size 설정을 확인하고, PHP 또는 애플리케이션이 요청을 처리하는 환경에서는 각 계층의 업로드 제한도 함께 점검해야 합니다.

특히 Nginx 설정을 변경했는데도 413 오류가 계속된다면 다른 server·location 설정, CDN·로드밸런서, 애플리케이션 자체 제한을 확인해야 합니다.

핵심은 오류 발생 위치 확인 → 요청 크기 제한 점검 → 필요한 범위만 설정 변경 → nginx -t 검증 → 실제 업로드 테스트 순서를 지키는 것입니다.