Nginx 413 Request Entity Too Large hatası nasıl çözülür?

Nginx dosya yükleme limitini doğru location içinde ayarlayın; client_max_body_size, config testi ve uygulama limitlerini birlikte doğrulayın.

Nginx arkasındaki uygulamaya dosya yüklerken 413 Request Entity Too Large hatası alıyorsanız, istek gövdesi bir katmanın kabul ettiği sınırı aşıyor olabilir. Yeni HTTP adlandırmalarında aynı durum 413 Content Too Large olarak da görülebilir.

Nginx kaynaklı durumda temel ayar client_max_body_size değeridir. Ancak uygulama, başka proxy veya CDN daha düşük limit kullanıyorsa yalnızca Nginx ayarını değiştirmek yeterli olmaz. Önce 413 yanıtını hangi katmanın ürettiğini belirleyin.

1. Yanıtın Nginx'ten geldiğini doğrulayın

İsteğin Network kaydını ve ilgili Nginx error log'unu aynı zaman aralığında inceleyin. client intended to send too large body benzeri mesaj, Nginx'in gövde sınırını uyguladığını gösterir. Yanıttaki Server başlığı tek başına kesin kanıt değildir; proxy başlıkları değiştirilebilir.

Aradaki CDN, ingress veya farklı bir reverse proxy de isteği uygulamaya ulaşmadan reddedebilir. Nginx log'unda kayıt yoksa yanlış sunucunun config'ini düzenlemek yerine istek yolunu izleyin. Uygulama log'unda 413 varsa onun yükleme ve parser limitlerini araştırın.

2. Doğru server veya location içinde limiti ayarlayın

client_max_body_size http, server veya location bağlamında kullanılabilir. Varsayılan değer 1m'dir. Aşağıdaki örnek, yükleme endpoint'i için 25 MB civarında bir gövde sınırı belirler:

server {
    listen 80;
    server_name app.example.com;

    location /api/upload {
        client_max_body_size 25m;
        proxy_pass http://127.0.0.1:3000;
    }
}

Bu bir yapılandırma parçasıdır; kendi mevcut server bloğunuzdaki doğru location'a uyarlayın. proxy_pass örneğinin sonunda eğik çizgi yoktur; URI'nin uygulamaya iletilme davranışını mevcut route'larla birlikte koruyun. HTTPS kullanan sistemde isteği işleyen 443 server bloğunu düzenleyin.

Bu sınır yalnızca dosyanın büyüklüğünü değil, HTTP istek gövdesinin tamamını kapsar. Multipart başlıkları ve diğer alanlar da gövdeye dahildir. Uygulamanız 20 MB dosya kabul ediyorsa Nginx gövde sınırını dosya limitinden biraz yüksek tutup dosya başına asıl sınırı uygulamada denetlemek daha anlaşılır sonuç verir.

3. Etkin yapılandırmayı ve sözdizimini kontrol edin

sudo nginx -T
sudo nginx -t

nginx -T include edilen dosyalarla birlikte etkin yapılandırmayı gösterir. Çıktı özel bilgiler içerebilir; herkese açık paylaşmayın. Daha özel bir location içinde düşük limit varsa üst bağlamdaki değeri geçersiz kılabilir. Sadece düzenlediğiniz dosyayı değil, isteğin eşleştiği bloğu kontrol edin.

nginx -t başarılı olduktan sonra systemd kullanan Linux sunucuda:

sudo systemctl reload nginx

Farklı kurulumlarda yeniden yükleme yöntemi değişir; Nginx'in sinyal yöntemi veya konteyner servisinizin normal dağıtım akışı kullanılabilir. Syntax hatası varken yeniden yüklemeyi zorlamayın. Reload sonrasında error log'u kontrol edin.

4. Docker içindeki ayarı kalıcılaştırın

Nginx konteyneri kullanıyorsanız ayarı yalnızca çalışan konteynerin içine yazmak, yeniden oluşturulduğunda kaybolabilir. Host üzerindeki versioned config'i bind mount ile bağlayın veya image içine ekleyin. Sonra ilgili konteyner içinde config testi yapın ve dağıtım akışınızla yeniden yükleyin.

Kubernetes ingress kullanan kurulumlarda denetleyicinin kendi yapılandırma seçenekleri geçerlidir. Düz Nginx config örneğini bütün ingress ürünlerine aynı biçimde kopyalamayın; kullandığınız controller'ın belgelediği gövde sınırı ayarını kontrol edin.

5. Uygulama ve üst proxy limitlerini eşleştirin

PHP'de upload ve POST limitleri, ASP.NET Core'da request body ve multipart sınırları, Express'te body parser veya dosya yükleme middleware'i ayrı katmanlardır. CDN'nin sabit plan limiti varsa Nginx bu üst sınırı kaldıramaz. Kabul edilen boyutu bütün yol boyunca belirleyin.

client_body_buffer_size bellek tamponuyla, proxy_read_timeout zaman aşımıyla ilgilidir; bunlar gövde boyutu limitinin yerine geçmez. client_max_body_size 0 Nginx'in bu kontrolünü kapatır. İhtiyacı karşılayan ölçülü bir sınır, sınırsız yüklemeden daha uygun bir başlangıçtır.

Çözümü sınırın iki tarafında test edin

Kimlik doğrulaması dahil gerçek yükleme akışıyla, kabul edilen boyutun altında ve üstünde iki dosya deneyin. Küçük dosya başarılı olmalı; büyük dosyada uygulamanın anlaşılır limit mesajı görünmelidir. Frontend doğrulaması kullanıcı deneyimini iyileştirir, sunucu sınırının yerini almaz.