502, 504 ve diğer Nginx hataları: nedenleri ve çözümleri

• Sunucu ve Altyapı
• Güncelleme: 04.10.2026
• Yaklaşık 10 dk okuma

Hata nerede doğuyor, nasıl teşhis edilir?

1. 1

   Hatanın nerede doğduğunu belirleyin

   Bir istek üç duraktan geçer: istemci (tarayıcı), Nginx ve arka uç (PHP-FPM, Node.js, Python gibi uygulamayı çalıştıran süreç). Her kod bu duraklardan birine işaret eder:

   • Nginx'in kendi kararı: 403, 404 (statik dosyalarda), 413. İstek arka uca hiç gitmemiş olabilir.
   • Nginx ile arka uç arasında: 502 ve 504. Nginx çalışıyor, ama arkadaki uygulamadan düzgün yanıt alamıyor.
   • Uygulamanın içinde: 500 ve uygulamanın döndürdüğü 404 ya da 403. Nginx bu yanıtı olduğu gibi iletir.
   • İstemci tarafında: 499. İstemci yanıtı beklemeden bağlantıyı kapatmıştır.

   : Büyüt

2. 2

   Günlükleri okuyun

   Nginx iki günlük tutar. Erişim günlüğü (access.log) her isteği durum koduyla birlikte kaydeder: hangi adres, ne zaman, hangi kodla sonuçlandı? Hata günlüğü (error.log) ise sorunun nedenini yazar. Çoğu kurulumda ikisi de /var/log/nginx/ altındadır; barındırma panelleri siteye özel günlükleri farklı bir klasörde tutabilir. Kesin yol, yapılandırmadaki access_log ve error_log yönergelerinde (directive) yazar.

   Bash

   # Hata günlüğünün son 50 satırı (yol çoğu kurulumda böyledir)
   sudo tail -n 50 /var/log/nginx/error.log
   
   # Günlüğü canlı izleyin; bu sırada hatayı tarayıcıda yineleyin
   sudo tail -f /var/log/nginx/error.log
   
   # Erişim günlüğünün son satırları: istek, durum kodu, boyut
   sudo tail -n 50 /var/log/nginx/access.log

   Hata günlüğündeki satırda genellikle sorunun kendisi (ör. connect() failed), isteğin adresi ve upstream: ile başlayan arka uç adresi bulunur. Bu satır, aşağıdaki bölümlerde hangi nedene bakacağınızı söyler.

3. 3

   502 ile 504'ü ayırt edin

   İkisi de "arka uçla ilgili bir sorun var" der, ama farklı şeyleri anlatır. 502, Nginx'in arka uca bağlanamadığını ya da bağlantının yanıt gelmeden koptuğunu gösterir; hata çoğunlukla hemen gelir. 504, bağlantının kurulduğunu ama yanıtın zaman aşımı (timeout) süresinde gelmediğini gösterir; hata, bekleme süresi dolduktan sonra gelir (varsayılan 60 saniye).

   : Büyüt

4. 4

   Sırayla teşhis edin

   1. Kodu, adresi ve saati not edin. Hata her istekte mi, yalnızca belirli bir sayfada mı, yalnızca yoğun saatlerde mi oluyor?
   2. Hata günlüğünde o saate bakın. Satır yoksa kod büyük olasılıkla uygulamadan gelmiştir.
   3. Arka uç ayakta mı? Hizmetin durumuna bakın.
   4. Arka ucu Nginx'i atlayarak deneyin. Sunucunun içinden doğrudan uygulamanın adresine istek atın: yanıt geliyor mu, ne kadar sürede geliyor?
   5. Yapılandırmayı gözden geçirin. Adres ve bağlantı noktası doğru mu, sınırlar ve zaman aşımları uygun mu, dosya izinleri yeterli mi?
   6. Düzeltin, test edin, yeniden yükleyin.

   Bash

   # Nginx çalışıyor mu?
   sudo systemctl status nginx
   
   # Arka uç hizmeti çalışıyor mu? (hizmet adını kendinize göre değiştirin)
   sudo systemctl status php-fpm
   
   # Arka ucu Nginx'i atlayarak deneyin (HTTP ile dinleyen uygulamalar için)
   curl -I http://127.0.0.1:3000/
   
   # Aynı adresi Nginx üzerinden deneyin
   curl -I http://ornek.com/

   Hizmet adı sisteme göre değişir; PHP-FPM hizmetinin adı çoğunlukla sürüm numarası içerir. Arka uç adresini kendi yapılandırmanızdaki proxy_pass satırından alın.

   : Büyüt

5. 5

   Kodu tanıyın ve ilgili bölüme geçin

   Aşağıdaki tablo en sık görülen kodları özetler; her birinin ayrıntısı alttaki bölümlerdedir.

   Kod	Anlamı	En sık neden	İlk bakılacak yer
   502	Bad Gateway: arka uçtan geçerli yanıt alınamadı	Uygulama çalışmıyor, yanlış adres ya da soket	error.log, hizmet durumu
   504	Gateway Timeout: arka uç zamanında yanıt vermedi	Yavaş sorgu ya da işlem, kısa zaman aşımı	error.log, uygulama günlüğü
   413	Request Entity Too Large: istek gövdesi çok büyük	client_max_body_size sınırı	Yapılandırma
   499	İstemci bağlantıyı kapattı (Nginx'e özgü)	Yavaş yanıt, sabırsız istemci ya da öndeki katmanın zaman aşımı	access.log
   403	Forbidden: erişim izni yok	Dosya izinleri, dizin dosyası yok, deny kuralı	error.log
   404	Not Found: adres bulunamadı	Yanlış root, eksik dosya, eşleşmeyen location	error.log, uygulama
   500	Internal Server Error: sunucu içi hata	Uygulama hatası, yönlendirme döngüsü	Uygulama günlüğü
   503	Service Unavailable: hizmet geçici olarak yok	Oran ya da bağlantı sınırı, bakım kipi	error.log

   : Büyüt

502 Bad Gateway

Ne demek? Nginx isteği arka uca iletmeye çalıştı, ancak bağlanamadı ya da geçerli bir yanıt alamadı.

Olası nedenler ve günlükteki izleri:

• Arka uç çalışmıyor ya da çökmüş: günlükte connect() failed (111: Connection refused) görülür.
• Adres, bağlantı noktası ya da soket yolu yanlış: proxy_pass ya da fastcgi_pass uygulamanın gerçekten dinlediği yeri göstermiyor. Soket dosyası yoksa No such file or directory yazar.
• Soket izni yok: connect() to unix:… failed (13: Permission denied). Nginx'in çalıştığı kullanıcı soket dosyasına erişemiyor. SELinux açık sistemlerde güvenlik ilkesi de bağlantıyı engelleyebilir.
• Arka uç yanıt vermeden bağlantıyı kapattı: upstream prematurely closed connection. Uygulama süreci istek sırasında çökmüş, yeniden başlatılmış ya da bellek sınırına takılmış olabilir.
• Yanıt başlıkları tampona sığmadı: upstream sent too big header. Çok büyük çerezler ya da başlıklar buna yol açar; proxy_buffer_size değeri artırılır.

Çözüm: Hizmeti başlatın ve neden durduğunu uygulamanın günlüğünden öğrenin. Adresi uygulamanın dinlediği adresle eşleştirin. Dağıtım ya da yeniden başlatma sırasında birkaç saniyelik 502 olağandır; sürekli yineleniyorsa uygulama çöküyordur. PHP sitelerinde ayrıntı için Nginx ve PHP-FPM rehberine bakın.

504 Gateway Timeout

Ne demek? Nginx arka uca bağlandı ve isteği gönderdi, ancak yanıt beklenen sürede gelmedi. Günlükte upstream timed out (110: Connection timed out) yazar.

Olası nedenler: yavaş bir veritabanı sorgusu; uygulamanın çağırdığı ve yanıt vermeyen bir dış hizmet; uzun süren rapor, dışa aktarma ya da toplu işlem; yoğunluk nedeniyle tüm uygulama süreçlerinin meşgul olması; arka uç başka bir sunucudaysa güvenlik duvarının bağlantıyı sessizce düşürmesi.

Teşhis: Hangi adreslerin zaman aşımına uğradığına bakın: tek bir sayfa mı, tüm site mi? Arka ucu doğrudan deneyip sürenin ne kadar olduğunu ölçün. Erişim günlüğüne arka uç süresini eklemek yavaş adresleri bulmayı kolaylaştırır:

# http düzeyinde: istek süresi ve arka uç süresi içeren günlük biçimi
log_format zamanli '$remote_addr [$time_local] "$request" $status '
                   'istek=$request_time arkauc=$upstream_response_time '
                   'arkauc_durum=$upstream_status';

server {
    listen 80;
    server_name ornek.com;

    access_log /var/log/nginx/access.log zamanli;

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

Çözüm: Önce yavaşlığın nedenini giderin (sorgu, dizin, önbellek). Uzun sürmesi doğal olan işleri arka plana alın ve kullanıcıya hemen yanıt dönün. Gerçekten gerekiyorsa yalnız ilgili adres için süreyi uzatın:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_connect_timeout 5s;    # bağlantı kurulamıyorsa uzun beklemeyin
    proxy_read_timeout    60s;   # varsayılan değer
}

# Yalnız uzun süren rapor adresi için daha uzun bekleme
location /rapor/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_read_timeout 180s;
}

Vekil bağlantılarında süreyi proxy_read_timeout, PHP-FPM'de fastcgi_read_timeout belirler; ikisinin de varsayılanı 60 saniyedir. Uygulamanın kendi süre sınırı (PHP'de max_execution_time gibi) daha kısaysa onu da gözden geçirin. Nginx'in önünde bir CDN ya da yük dengeleme (load balancing) katmanı varsa onun da kendi zaman aşımı vardır; Nginx'teki süreyi uzatmak o katmanı etkilemez.

413 Request Entity Too Large

Ne demek? İstemcinin gönderdiği istek gövdesi (çoğunlukla yüklenen dosya) izin verilen boyutu aşıyor. Sınırı client_max_body_size belirler; varsayılan değer 1m, yani 1 megabayttır. Günlükte client intended to send too large body yazar.

# Tüm site için istek gövdesi sınırı (varsayılan 1m)
client_max_body_size 2m;

# Yalnız dosya yükleme adresi için daha yüksek sınır
location /yukle/ {
    client_max_body_size 50m;
    proxy_pass http://127.0.0.1:3000;
}

Çözüm: Sınırı gerçek gereksiniminize göre yükseltin; yönerge http, server ya da location düzeyinde yazılabilir. Sınırı yalnız yükleme adresi için yükseltmek, tüm site için yükseltmekten güvenlidir. Uygulamanın kendi sınırlarını da eşleştirin: PHP'de upload_max_filesize ve post_max_size daha küçükse yükleme bu kez PHP tarafında reddedilir. Yüklenen dosyaların denetimi için dosya yükleme güvenliği rehberine bakın.

499: istemci bağlantıyı kapattı

Ne demek? 499 standart bir HTTP kodu değildir; Nginx'e özgüdür ve yalnızca erişim günlüğünde görülür. İstemci, Nginx yanıtı gönderemeden bağlantıyı kapatmıştır; ortada yanıtı alacak kimse kalmadığı için ziyaretçi bu kodu hiç görmez.

Olası nedenler: ziyaretçi sayfayı kapattı, yeniledi ya da başka sayfaya geçti; mobil uygulamanın ya da API istemcisinin kendi zaman aşımı Nginx'inkinden kısa; Nginx'in önündeki CDN ya da yük dengeleyici beklemekten vazgeçti.

Teşhis ve çözüm: Tek tük 499 olağandır. Belirli bir adreste yoğunlaşıyorsa o adres yavaş yanıt veriyordur: asıl sorun hızdır, 504 bölümündeki adımları uygulayın. Öndeki katmanın zaman aşımı ile Nginx'in zaman aşımını birbirine uyumlu tutun.

403 Forbidden

Ne demek? Sunucu isteği anladı ama yerine getirmeyi reddediyor.

• Dosya izinleri: günlükte (13: Permission denied). Nginx'in çalıştığı kullanıcı dosyayı okuyabilmeli ve dosyaya giden tüm üst klasörlerde geçiş (x) iznine sahip olmalıdır.
• Dizin dosyası yok: günlükte directory index of … is forbidden. Klasör istendi, index yönergesinde yazan dosyalardan hiçbiri bulunamadı ve dizin listeleme kapalı. root yolunu ve index satırını kontrol edin.
• Erişim kuralı: günlükte access forbidden by rule. Bir deny kuralı isteği engelledi; kural bilerek yazıldıysa (ör. gizli dosyalar) bu beklenen davranıştır.
• Uygulamanın kararı: Günlükte satır yoksa 403'ü uygulama (yetki kontrolü) ya da öndeki bir güvenlik katmanı döndürmüş olabilir.

İzin sorununu "herkese tam yetki" vererek çözmeyin; doğru sahiplik ve en az yetki için sunucu ve barındırma güvenliği rehberine bakın.

404 Not Found

Ne demek? İstenen adresin karşılığı bulunamadı.

• Dosya gerçekten yok ya da root yanlış: günlükte open() "…" failed (2: No such file or directory). Satırdaki tam yol, Nginx'in dosyayı nerede aradığını gösterir; çoğu yapılandırma hatası bu yola bakınca anlaşılır.
• Yanlış location eşleşti: İstek, beklediğinizden farklı bir bloğa düşüyor olabilir.
• Tek giriş noktalı uygulamalar: Tüm adresleri index.php gibi tek dosyanın karşıladığı uygulamalarda try_files satırı eksikse ana sayfa açılır, diğer sayfalar 404 verir.
• Vekil arkasında yol uyumsuzluğu: 404'ü uygulama döndürüyorsa Nginx hata günlüğünde satır olmaz. proxy_pass sonundaki eğik çizgi arka uca giden yolu değiştirir; ayrıntısı ters vekil kurulumu rehberindedir.

500 ve 503 kısaca

500 Internal Server Error çoğunlukla uygulamadan gelir: yakalanmamış bir hata, bozuk bir yapılandırma dosyası ya da veritabanı bağlantı sorunu. Nedeni uygulamanın ya da PHP'nin hata günlüğündedir. Nginx'in kendisi 500'ü nadiren üretir; bunun tipik örneği, günlükte rewrite or internal redirection cycle olarak görülen iç yönlendirme döngüsüdür.

503 Service Unavailable hizmetin geçici olarak karşılanamadığını bildirir. Nginx bu kodu oran sınırlama (limit_req) ya da bağlantı sınırı (limit_conn) aşıldığında varsayılan olarak döndürür; günlükte limiting requests ya da limiting connections yazar. Bakım kipinde bilerek döndürülen yanıt da 503'tür. Uygulamanın kendisi de aşırı yük altında 503 dönebilir.

Ani ve yaygın 502, 503, 504 artışı yoğun bot trafiğinin belirtisi de olabilir; bkz. DDoS ve bot saldırıları.

Değişiklikten sonra

Yapılandırmada yaptığınız her değişikliği önce test edin, sonra yeniden yükleyin. Test başarısızsa Nginx hatalı satırın dosyasını ve numarasını yazar; yeniden yükleme yapılmadığı sürece site eski ayarlarla çalışmayı sürdürür.

# Yapılandırmayı test edin
sudo nginx -t

# Test başarılıysa yeniden yükleyin
sudo systemctl reload nginx

Ziyaretçiye gösterilen hata sayfasında sürüm, dosya yolu ya da hata ayrıntısı bulunmamalıdır; ayrıntı günlükte kalır. Sorun çözüldükten sonra günlükleri birkaç gün izleyin: aynı satır yineleniyorsa neden hâlâ yerindedir.

Sık sorulan sorular

İlgili rehberler

• Nginx ile reverse proxy (ters vekil) kurulumuserver bloğu, proxy_pass, iletilecek başlıklar, WebSocket, zaman aşımları ve gerçek IP ayarıyla adım adım kurulum.
• Nginx ve PHP-FPM: PHP siteleri Nginx ile nasıl çalışır?fastcgi_pass, SCRIPT_FILENAME, try_files, havuz (pool) kavramı, soket izinleri ve 502 hatası.
• Nginx nedir, ne işe yarar?Nginx'in rolleri, olay tabanlı mimarisi, Apache ile farkı, yapılandırma blokları ve temel komutlar.
• DDoS ve bot saldırılarıBelirtiler, CDN ve WAF, oran sınırlama, önbellek ve barındırma sağlayıcıyla birlikte hareket etme.