رفع 413 Request Entity Too Large در Nginx با client_max_body_size

اگر هنگام آپلود فایل، ارسال فرم یا Request بزرگ در Nginx با خطای 413 Request Entity Too Large یا 413 Payload Too Large روبه‌رو شده‌اید، معنی آن معمولاً این است که اندازه Body درخواست از سقفی که Nginx اجازه می‌دهد بیشتر است. در Nginx این محدودیت با Directiveای به نام client_max_body_size کنترل می‌شود؛ مقدار پیش‌فرض آن طبق مستندات رسمی 1m است.

خطای 413 Request Entity Too Large چیست؟

وقتی Client مثل Browser، اپ موبایل یا API Client یک Request با Body بزرگ به سرور می‌فرستد، Nginx قبل از Forward کردن آن به Backend می‌تواند اندازه Request Body را بررسی کند.

اگر حجم Request از مقدار مجاز بیشتر باشد، Nginx پاسخ 413 می‌دهد.

نمونه:

413 Request Entity Too Large
nginx

این خطا معمولاً در این سناریوها دیده می‌شود:

• آپلود فایل در WordPress
• آپلود Backup
• ارسال فایل در Laravel
• آپلود ویدئو یا تصویر بزرگ
• API با JSON یا Multipart بزرگ
• آپلود فایل در پنل مدیریت
• ارسال فایل از اپ موبایل
• Reverse Proxy جلوی یک سرویس Upload

محدودیت پیش‌فرض Nginx چقدر است؟

Directive اصلی:

client_max_body_size

مقدار پیش‌فرض طبق مستندات Nginx:

client_max_body_size 1m;

یعنی اگر تنظیم دیگری وجود نداشته باشد، Request Body بزرگ‌تر از حدود ۱ مگابایت می‌تواند با 413 رد شود.

مرحله اول: فایل Configuration فعال سایت را پیدا کنید

در Ubuntu و Debian معمولاً فایل‌های Virtual Host در این مسیرها هستند:

/etc/nginx/sites-available/
/etc/nginx/sites-enabled/

برای دیدن کل Configuration فعال Nginx:

sudo nginx -T

برای پیدا کردن همه تنظیمات مربوط به حداکثر Body:

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

این مرحله مهم است؛ چون ممکن است شما یک فایل را تغییر دهید اما سایت از Virtual Host دیگری استفاده کند.

روش اول: تنظیم client_max_body_size در server

برای یک سایت مشخص، معمولاً مناسب‌ترین محل داخل Block مربوط به server است.

مثال:

server {
    listen 80;
    server_name example.com;

    client_max_body_size 50M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
}

در این مثال سقف Request Body برای کل آن Virtual Host برابر ۵۰ مگابایت است.

روش دوم: محدودیت فقط برای یک مسیر Upload

اگر فقط یک Endpoint برای Upload فایل بزرگ دارید، بهتر است محدودیت بزرگ را فقط همان‌جا اعمال کنید.

مثال:

location /upload/ {
    client_max_body_size 200M;

    proxy_pass http://127.0.0.1:3000;
}

این روش معمولاً از تنظیم یک مقدار بسیار بزرگ برای همه Requestهای سایت منطقی‌تر است.

آیا می‌توان client_max_body_size را در http قرار داد؟

بله. Nginx اجازه استفاده از این Directive را در Contextهای زیر می‌دهد:

• http
• server
• location

برای تنظیم سراسری:

http {
    client_max_body_size 50M;

    ...
}

اما اگر فقط یک سایت به Upload بزرگ نیاز دارد، تنظیم در سطح server یا location کنترل بیشتری می‌دهد.

آیا می‌توان محدودیت را کاملاً غیرفعال کرد؟

Nginx اجازه می‌دهد مقدار را صفر کنید:

client_max_body_size 0;

مقدار صفر یعنی بررسی اندازه Request Body توسط این Directive غیرفعال شود.

بعد از تغییر حتماً nginx -t اجرا کنید

قبل از Reload:

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

چطور مطمئن شویم مقدار جدید واقعاً فعال شده است؟

دوباره Configuration نهایی را ببینید:

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

اگر چند مقدار می‌بینید، Context مهم است. یک location می‌تواند مقدار تعریف‌شده در سطح بالاتر را Override کند.

لاگ Nginx را بررسی کنید

Error Log معمولاً:

/var/log/nginx/error.log

آخرین خطوط:

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

ممکن است پیامی شبیه این ببینید:

client intended to send too large body:
10485760 bytes,
client: 203.0.113.10,
server: example.com,
request: "POST /upload HTTP/1.1"

این پیام تقریباً مستقیم نشان می‌دهد Nginx به دلیل اندازه Body درخواست را رد کرده است.

اگر سایت PHP است، فقط Nginx کافی نیست

در PHP حداقل دو Directive مهم وجود دارد:

upload_max_filesize
post_max_size

مثال:

upload_max_filesize = 50M
post_max_size = 60M

post_max_size باید از upload_max_filesize بزرگ‌تر باشد، چون کل POST Request فقط شامل خود فایل نیست و Metadata و Fieldهای دیگر نیز داخل آن هستند.

همچنین در بسیاری از سناریوها بهتر است memory_limit نیز از post_max_size بزرگ‌تر باشد.

کدام php.ini را باید ویرایش کنیم؟

برای PHP CLI:

php --ini

اما اگر سایت با PHP-FPM اجرا می‌شود، Configuration FPM ممکن است فایل دیگری باشد.

مثلاً در PHP 8.3 روی Ubuntu:

/etc/php/8.3/fpm/php.ini

بعد از تغییر:

sudo systemctl restart php8.3-fpm

نام Service را با نسخه واقعی PHP سرور خودتان تطبیق دهید.

مقادیر فعال PHP را ببینید

برای CLI:

php -i | grep -E 'upload_max_filesize|post_max_size|memory_limit'

اما توجه کنید مقدار CLI الزاماً با PHP-FPM یکسان نیست. برای سایت Production بهتر است مقادیر Runtime خود FPM را بررسی کنید.

رفع 413 در WordPress

اگر هنگام Upload در WordPress با 413 مواجه می‌شوید، حداقل این سه لایه را بررسی کنید:

1. Nginx: client_max_body_size
2. PHP: upload_max_filesize
3. PHP: post_max_size

نمونه هماهنگ:

# Nginx
client_max_body_size 64M;

# PHP
upload_max_filesize = 50M
post_max_size = 60M
memory_limit = 256M

در این مثال Nginx سقف بالاتری از PHP دارد تا Request قبل از رسیدن به PHP توسط Nginx قطع نشود.

رفع 413 در Laravel

در Laravel اگر Nginx Request را رد کند، Request اصلاً به Application نمی‌رسد. بنابراین Validation داخل Laravel هنوز اجرا نشده است.

اول Nginx را اصلاح کنید:

client_max_body_size 50M;

بعد PHP را هماهنگ کنید:

upload_max_filesize = 40M
post_max_size = 50M

سپس Validation خود Laravel را هم بر اساس نیاز پروژه تنظیم کنید تا Application مستقل از Web Server محدودیت منطقی داشته باشد.

رفع 413 در Node.js و Express

اگر Nginx جلوی Node.js قرار دارد، Nginx یکی از لایه‌های محدودیت است؛ اما Express یا Middleware نیز ممکن است Limit جداگانه داشته باشند.

مثلاً برای JSON:

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

یا برای URL-encoded Body:

app.use(express.urlencoded({
    extended: true,
    limit: '10mb'
}));

اگر Nginx روی 50M تنظیم باشد اما Express فقط 10MB اجازه دهد، خطای Nginx برطرف می‌شود اما Application همچنان Request بزرگ‌تر از 10MB را رد می‌کند.

اگر چند Reverse Proxy دارید

در بعضی معماری‌ها مسیر Request این‌طور است:

Client
  ↓
CDN / Load Balancer
  ↓
Nginx
  ↓
Application

هر لایه ممکن است محدودیت Upload خودش را داشته باشد.

اگر Nginx را روی 100M تنظیم کردید ولی 413 همچنان باقی ماند، باید مشخص کنید پاسخ 413 دقیقاً از کدام لایه می‌آید.

چطور بفهمیم 413 از Nginx است یا Backend؟

Header پاسخ را ببینید:

curl -i -X POST https://example.com/upload

هم‌زمان Nginx Error Log را Tail کنید:

sudo tail -f /var/log/nginx/error.log

اگر پیام client intended to send too large body ثبت شود، Nginx علت خطاست.

تست Upload با curl

برای تست واقعی یک فایل:

curl -v \
  -F "file=@/path/to/test.zip" \
  https://example.com/upload

اگر API شما Auth نیاز دارد، Headerهای لازم را نیز اضافه کنید.

client_body_buffer_size با client_max_body_size فرق دارد

این دو Directive را با هم اشتباه نگیرید.

client_max_body_size سقف مجاز Request Body است.

client_body_buffer_size مشخص می‌کند چه مقدار از Request Body در Buffer حافظه نگهداری شود؛ اگر Body بزرگ‌تر باشد، Nginx می‌تواند آن را در Temporary File بنویسد.

بالا بردن client_body_buffer_size جایگزین افزایش client_max_body_size نیست.

Disk Space را برای Upload بزرگ بررسی کنید

اگر Request Body بزرگ‌تر از Buffer باشد، Nginx ممکن است بخشی از آن را در فایل موقت ذخیره کند. بنابراین فضای دیسک نیز اهمیت دارد.

df -h

اگر پارتیشن مربوط به Temporary Files پر باشد، Upload بزرگ ممکن است با خطاهای دیگری مواجه شود.

مسیر Temporary Body در Nginx

Nginx می‌تواند Request Bodyهای بزرگ را در Temporary File ذخیره کند. Directive مرتبط:

client_body_temp_path

برای مشاهده تنظیم فعال:

sudo nginx -T 2>&1 | grep client_body_temp_path

اگر مقدار خاصی تعریف نشده، Nginx از مسیرهای پیش‌فرض Build یا Package استفاده می‌کند.

اگر Temporary Path Permission ندارد

در این حالت معمولاً خطای 413 اصلی نیست، اما Upload بزرگ می‌تواند در مرحله بعدی Fail شود. Owner و Permission مسیر موقت را بررسی کنید و آن را با User واقعی Nginx هماهنگ نگه دارید.

User فعال Nginx را می‌توانید از Configuration ببینید:

grep -n '^user' /etc/nginx/nginx.conf

رفع 413 در Nginx داخل Docker

اگر Nginx داخل Container اجرا می‌شود، تغییر فایل Host فقط زمانی اثر دارد که همان فایل داخل Container Mount شده باشد.

کانتینر را پیدا کنید:

docker ps

Configuration داخل Container:

docker exec NGINX_CONTAINER nginx -T

اگر Compose دارید:

docker compose exec nginx nginx -T

بعد از اصلاح Configuration:

docker compose exec nginx nginx -t
docker compose exec nginx nginx -s reload

Nginx Proxy Manager و پنل‌های مشابه

اگر از پنلی استفاده می‌کنید که Configuration Nginx را خودکار تولید می‌کند، ویرایش مستقیم فایل تولیدشده ممکن است بعداً Overwrite شود.

در این حالت باید Custom Nginx Configuration همان Host را از داخل پنل تنظیم کنید.

Directive اصلی همچنان:

client_max_body_size 100M;

آپلود Backup یا Import در WordPress

برای Importهای بزرگ WordPress فقط Nginx کافی نیست. Plugin مورد استفاده نیز ممکن است محدودیت داخلی خودش را داشته باشد.

بنابراین این زنجیره را بررسی کنید:

Nginx limit
↓
PHP post_max_size
↓
PHP upload_max_filesize
↓
WordPress / Plugin limit

آیا مقدار خیلی بزرگ خطر امنیتی دارد؟

بزرگ کردن سقف Upload ذاتاً آسیب‌پذیری نیست، اما سطح مصرف منابع را بالا می‌برد. یک مهاجم می‌تواند Requestهای بزرگ زیادی ارسال کند و پهنای باند، Disk I/O یا منابع Backend را مصرف کند.

برای Endpointهای Public بهتر است:

• سقف واقعی و محدود تعریف کنید.
• Authentication داشته باشید.
• Rate Limit مناسب در نظر بگیرید.
• نوع فایل را Validate کنید.
• حجم فایل را در Application هم بررسی کنید.

چه مقداری برای client_max_body_size انتخاب کنیم؟

عدد ثابت و جهانی وجود ندارد. مقدار باید بر اساس کاربرد باشد.

مثلاً:

# تصاویر معمولی
client_max_body_size 20M;

# فایل‌های Backup یا ZIP
client_max_body_size 200M;

# Upload محدود به یک API خاص
location /api/upload {
    client_max_body_size 100M;
}

هدف این است که Limit کمی بالاتر از بیشترین Payload مجاز Application باشد، نه اینکه بی‌دلیل چند گیگابایت تعیین شود.

نمونه کامل Nginx برای PHP-FPM

server {
    listen 80;
    server_name example.com;

    root /var/www/example/public;
    index index.php index.html;

    client_max_body_size 64M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
}

بعد:

sudo nginx -t
sudo systemctl reload nginx

نمونه کامل برای Reverse Proxy

server {
    listen 443 ssl;
    server_name api.example.com;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:3000;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

ترتیب پیشنهادی عیب‌یابی

1. Error Log را برای client intended to send too large body بررسی کنید.
2. با nginx -T Configuration فعال را پیدا کنید.
3. client_max_body_size را در Scope مناسب تنظیم کنید.
4. با nginx -t Syntax را تست کنید.
5. Nginx را Reload کنید.
6. اگر PHP دارید، upload_max_filesize و post_max_size را هماهنگ کنید.
7. اگر Node.js یا Framework دیگری دارید، Body Limit داخلی آن را بررسی کنید.
8. Upload واقعی را با Browser یا curl تست کنید.
9. Disk Space و Temporary Storage را برای Uploadهای بزرگ بررسی کنید.
10. اگر 413 باقی ماند، CDN، Load Balancer یا Proxy بالادستی را بررسی کنید.

Rollback؛ اگر تغییر Configuration مشکل ایجاد کرد

قبل از تغییر فایل سایت بکاپ بگیرید:

sudo cp /etc/nginx/sites-available/example.com \
  /etc/nginx/sites-available/example.com.backup

برای بازگردانی:

sudo cp /etc/nginx/sites-available/example.com.backup \
  /etc/nginx/sites-available/example.com

sudo nginx -t
sudo systemctl reload nginx

اشتباه‌های رایج

• تنظیم client_max_body_size در فایل اشتباه؛
• فراموش کردن nginx -t قبل از Reload؛
• افزایش Nginx Limit ولی تغییر ندادن PHP؛
• کمتر بودن post_max_size از upload_max_filesize؛
• استفاده از client_max_body_size 0 بدون نیاز واقعی؛
• نادیده گرفتن محدودیت Express، Laravel یا Plugin؛
• نادیده گرفتن Proxy یا CDN بالادستی؛
• افزایش client_body_buffer_size به‌جای client_max_body_size؛
• فراموش کردن فضای Disk برای Temporary Body؛
• Restart کردن Nginx بدون بررسی Configuration فعال با nginx -T.

سؤالات متداول

خطای 413 Request Entity Too Large در Nginx یعنی چه؟

یعنی اندازه Request Body از مقدار مجاز Nginx بیشتر است. Directive اصلی کنترل‌کننده این محدودیت client_max_body_size است.

مقدار پیش‌فرض client_max_body_size چقدر است؟

طبق مستندات Nginx مقدار پیش‌فرض 1m است.

client_max_body_size را کجا قرار دهیم؟

این Directive در Contextهای http، server و location قابل استفاده است. برای یک سایت مشخص معمولاً server و برای یک Endpoint خاص معمولاً location انتخاب مناسب‌تری است.

آیا فقط با افزایش client_max_body_size مشکل WordPress حل می‌شود؟

نه همیشه. در WordPress باید محدودیت‌های PHP مثل upload_max_filesize و post_max_size و در بعضی موارد محدودیت Plugin نیز بررسی شوند.

آیا می‌توان client_max_body_size را صفر کرد؟

بله. مقدار صفر بررسی سقف Request Body توسط این Directive را غیرفعال می‌کند، اما در Production معمولاً بهتر است یک Limit واقعی و کنترل‌شده داشته باشید.

چرا بعد از افزایش Limit هنوز 413 می‌گیرم؟

ممکن است مقدار در Virtual Host فعال اعمال نشده باشد، Location دیگری آن را Override کرده باشد یا لایه بالادستی مثل CDN، Load Balancer یا Proxy دیگری Request را رد کند.

client_body_buffer_size همان client_max_body_size است؟

خیر. client_max_body_size سقف کل Request Body را تعیین می‌کند، اما client_body_buffer_size اندازه Buffer مورد استفاده برای خواندن Body را کنترل می‌کند.

برای PHP چه مقادیری باید هماهنگ باشند؟

post_max_size باید از upload_max_filesize بزرگ‌تر باشد. همچنین برای بسیاری از سناریوها بهتر است memory_limit نیز از post_max_size بزرگ‌تر باشد.