413 Request Entity Too Large 오류 해결하기 (Nginx & Node.js 환경)

웹 애플리케이션을 개발하다 보면 서버에서 설정한 요청 크기보다 큰 요청이 들어왔을 때 다음과 같은 오류를 마주할 수 있습니다.

413 Request Entity Too Large

이 오류는 서버가 처리할 수 있는 최대 요청 크기를 초과했을 때 발생합니다.
이번 글에서는 Node.js(Express)와 Nginx 환경에서 발생하는 413 Request Entity Too Large 오류의 원인과 해결 방법을 정리해 보겠습니다.

 

 

🛑 PayloadTooLargeError 발생 원인

이 오류는 서버가 허용하는 요청 크기를 초과한 경우 발생합니다. 일반적으로 다음과 같은 원인에서 비롯됩니다.

• Express의 요청 크기 제한 초과
  • Express에서는 기본적으로 JSON 및 URL-encoded 요청의 크기를 제한합니다.
• Nginx의 요청 크기 제한 설정
  • Nginx(Ingress Controller 포함)가 요청의 최대 크기를 제한할 수 있습니다.
• 쿠버네티스 환경에서 Ingress 설정 문제
  • Kubernetes에서 Nginx Ingress Controller를 사용할 경우, 기본 요청 크기 제한이 적용합니다.
• 클라이언트에서 너무 큰 요청을 전송
  • 클라이언트가 서버가 처리할 수 없는 크기의 파일을 업로드하는 경우 발생합니다.

 

🛠️  해결 방법

1️⃣  Express의 요청 크기 제한 설정 변경

기본적으로 Express는 JSON 및 URL-encoded 요청 크기를 제한합니다.
이제 요청 크기 제한을 늘리는 방법을 살펴보겠습니다!

 

Express의 express.json()과 express.urlencoded()의 limit 옵션을 조정하여 요청 크기를 늘릴 수 있습니다.

const express = require("express");
const app = express();

// 요청 크기 제한을 50MB로 증가
app.use(express.json({ limit: "50mb" }));
app.use(express.urlencoded({ limit: "50mb", extended: true }));

app.listen(3000, () => console.log("Server running on port 3000"));

💡limit 값을 요청에 맞게 조정하면 오류를 방지할 수 있다.

 

 

2️⃣ Nginx Ingress Controller의 proxy-body-size 설정 증가

Nginx는 기본적으로 요청 본문 크기를 제한하는 설정을 가지고 있습니다.
이 값이 너무 작으면, 클라이언트의 요청이 413 Request Entity Too Large 오류와 함께 차단됩니다.

 

쿠버네티스 환경에서 Nginx Ingress Controller를 사용한다면, Helm Chart의 values.yaml에서 proxy-body-size 값을 증가시켜야 합니다.

ingress: 
  enabled: true 
  annotations: 
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"

💡Ingress 설정을 변경한 후 반드시 kubectl apply를 실행하여 적용해야 한다.

 

3️⃣ 클라이언트에서 요청 크기 확인

때로는 서버가 허용하는 요청 크기보다 클라이언트가 너무 큰 요청을 보내는 경우도 문제의 원인이 됩니다.
이를 확인하려면 클라이언트에서 전송하는 요청 크기를 로깅하면 됩니다.

app.use((req, res, next) => { 
	console.log(`Request size: ${req.headers["content-length"] || "unknown"}`); 
    next(); 
});

💡클라이언트가 비정상적으로 큰 요청을 보낸다면, 요청 크기를 조정하는 것이 필요하다.

 

 

📍해결 방법 요약

해결 방법	적용 위치	예시
Express 요청 크기 증가	Node.js 서버	app.use(express.json({ limit: "50mb" }));
Nginx Ingress 요청 크기 증가	쿠버네티스 Ingress	nginx.ingress.kubernetes.io/proxy-body-size: "50m"
클라이언트 요청 크기 확인	모든 환경	console.log(req.headers["content-length"]);

 

 

413 Request Entity Too Large 오류는 서버에서 허용하는 요청 크기를 초과했을 때 발생하는 일반적인 문제입니다.
이 문제를 해결하기 위해서는 Express, Nginx, Ingress Controller의 설정을 적절히 조정하고, 클라이언트의 요청 크기를 확인하는 과정이 필요합니다.
서버가 너무 큰 요청을 적절히 처리할 수 있도록 고려해봅시다.🚀