Nginx 502 Bad Gateway Hatası Neden Oluşur?

502 Bad Gateway ne anlama gelir?

Nginx üzerinde görülen 502 Bad Gateway hatası, çoğunlukla Nginx’in arkasındaki uygulama veya servisten geçerli bir cevap alamadığını gösterir.

Bu hata her zaman Nginx’in çalışmadığı anlamına gelmez. Kullanıcıya 502 sayfasını gösterebildiğine göre Nginx çoğu durumda isteği kabul etmiş, fakat isteği yönlendirdiği backend servisle sağlıklı iletişim kuramamıştır.

Kullanıcı → Nginx → Backend uygulama → Veritabanı veya diğer servisler

İlk 5 dakikada uygulanacak teşhis sırası

Önce konfigürasyonun geçerli olduğunu, ardından Nginx error logundaki gerçek upstream hatasını ve backend’in dinlediği adresi doğrulayın. PORT değerini kendi upstream portunuzla değiştirin.

Komutları sırayla çalıştırın; ilk başarısız adım çoğunlukla incelemeniz gereken katmanı gösterir.

sudo nginx -t
sudo tail -n 80 /var/log/nginx/error.log
sudo ss -lntp
curl -sv --max-time 5 http://127.0.0.1:PORT/health

• nginx -t başarılı: syntax is ok ve test is successful görülür; hata varsa önce dosya ve satır numarasını düzeltin.
• Connection refused: hedef portta process dinlemiyor veya yanlış IP/port kullanılıyor.
• Connection timed out: firewall, network yolu ya da yanıt vermeyen backend incelenmeli.
• HTTP/1.1 200: backend yerelden cevap veriyor; Nginx upstream adresi, protokolü ve Host header’ı karşılaştırılmalı.
• HTTP 500/503: bağlantı kuruluyor; kök neden büyük olasılıkla uygulama veya bağımlılık katmanında.

Nginx error log çıktısını yorumlama

502 sayfasındaki metin kök nedeni söylemez; error logundaki aynı saniyeye ait upstream kaydı söyler. Aşağıdaki komut son kayıtları ve ilgili hata ifadelerini birlikte gösterir.

sudo grep -E "connect() failed|timed out|prematurely closed|no live upstreams|Permission denied" \
  /var/log/nginx/error.log | tail -n 50

• connect() failed (111: Connection refused): backend kapalı, yanlış portta veya yanlış adreste.
• upstream timed out: backend bağlantıyı kabul etmiş olabilir ancak süresinde cevap üretmemiştir.
• upstream prematurely closed connection: uygulama geçerli HTTP cevabı tamamlanmadan bağlantıyı kapatmıştır.
• no live upstreams: upstream grubundaki bütün hedefler kullanılamaz durumdadır.
• Permission denied while connecting to upstream: Unix socket, SELinux veya dosya/dizin izni kontrol edilmelidir.

Systemd ile çalışan backend servisini doğrulama

Backend bir systemd servisi ise yalnız active yazısına güvenmeyin; son logları ve gerçekten dinlenen portu birlikte kontrol edin. APP_SERVICE ve PORT değerlerini kendi ortamınıza göre değiştirin.

sudo systemctl status APP_SERVICE --no-pager
sudo journalctl -u APP_SERVICE --since "15 minutes ago" --no-pager
sudo ss -lntp | grep ':PORT'
curl -sS -o /dev/null -w '%{http_code} %{time_total}s\n' http://127.0.0.1:PORT/health

• active (running) + port listede + 200: servis yerelde sağlıklı; Nginx proxy ayarına geçin.
• failed veya restart counter artıyor: uygulama başlangıç logunu çözmeden Nginx restart etmeyin.
• Servis aktif fakat port yok: uygulama farklı porta bağlanmış, yalnız socket açmış veya henüz hazır değildir.

Docker ortamında Nginx’ten backend’e erişimi test etme

Nginx container içindeyse localhost Nginx container’ını ifade eder. Testi hosttan değil, Nginx’in bulunduğu network bağlamından yapın.

NGINX_CONTAINER, BACKEND_SERVICE ve PORT değerlerini Compose servislerinize göre değiştirin.

docker compose ps
docker compose logs --tail=100 BACKEND_SERVICE
docker inspect NGINX_CONTAINER --format '{{json .NetworkSettings.Networks}}'
docker inspect BACKEND_SERVICE --format '{{json .NetworkSettings.Networks}}'
docker exec NGINX_CONTAINER sh -c 'wget -S -O- http://BACKEND_SERVICE:PORT/health'

• Her iki inspect çıktısında ortak network yoksa container’lar birbirini servis adıyla çözemez.
• bad address veya could not resolve host: servis adı ya da Docker DNS/network bağlantısı yanlış.
• Connection refused: isim çözümleniyor fakat backend ilgili portu dinlemiyor.
• 200 OK: container ağı çalışıyor; Nginx location ve proxy_pass eşleşmesini inceleyin.

Aktif Nginx konfigürasyonunu karşılaştırma

Düzenlediğiniz dosya ile Nginx’in gerçekten yüklediği konfigürasyon farklı olabilir. nginx -T, include edilen bütün dosyaları birleştirerek aktif yapıyı gösterir.

sudo nginx -T 2>&1 | grep -nE 'server_name|location|proxy_pass|upstream'

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    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;
}

• proxy_pass hedefi ss veya Docker testiyle doğruladığınız adresle aynı olmalı.
• Backend HTTP dinliyorsa proxy_pass içinde https kullanmayın.
• Değişiklikten sonra önce sudo nginx -t çalıştırın; yalnız test başarılıysa sudo systemctl reload nginx kullanın.

Backend uygulamanın çalışmaması

Nginx isteği belirli bir IP adresine, porta veya Unix socket’e yönlendirir. Uygulama durmuşsa, sürekli yeniden başlıyorsa veya beklenen portu dinlemiyorsa Nginx bağlantı kuramaz.

Yalnızca Nginx’i yeniden başlatmak bu durumda kalıcı çözüm sağlamaz. Öncelikle upstream uygulamanın neden erişilemez olduğu belirlenmelidir.

• Deployment sonrasında başlamayan uygulama
• Sürekli yeniden başlayan container
• Yanlış portta çalışan servis
• Bellek yetersizliği nedeniyle sonlandırılan process
• Trafik almaya henüz hazır olmayan uygulama

Yanlış proxy_pass adresi veya portu

Adres, port veya protokol yanlışsa Nginx backend servise bağlantı kuramaz. Uygulamanın portu değişmiş fakat Nginx konfigürasyonu güncellenmemiş olabilir.

HTTP bekleyen bir servise HTTPS ile veya HTTPS bekleyen bir servise HTTP ile bağlanmak da geçerli cevap alınamamasına neden olabilir.

Docker network veya servis adı problemi

Nginx ve uygulama farklı container’larda çalışıyorsa localhost, Nginx container’ının kendisini ifade eder; backend uygulamayı değil.

Container’ın yalnızca Up görünmesi yeterli değildir. Nginx’in bulunduğu network bağlamından backend servise gerçekten erişilebildiği doğrulanmalıdır.

• Container’ların aynı network üzerinde olmaması
• Compose servis adının değişmesi
• Backend container’ın başlamaması
• Uygulamanın yalnız 127.0.0.1 üzerinde dinlemesi
• Nginx’in eski IP adresini kullanması

Backend servisin bağlantıyı erken kapatması

Nginx backend servise bağlanabilir, ancak uygulama geçerli bir HTTP cevabı göndermeden bağlantıyı kapatabilir. Error logunda upstream prematurely closed connection ifadesi görülebilir.

Bu kayıt yalnızca bağlantının kesildiğini söyler. Asıl kök neden çoğunlukla aynı zaman aralığındaki uygulama logunda bulunur.

• Beklenmeyen uygulama hatası
• Worker process’in çökmesi
• Bellek yetersizliği
• Uygulama içi timeout
• Veritabanı bağlantı problemi
• Deployment sırasında process’in sonlandırılması

Unix socket izinleri

Nginx; PHP-FPM, Gunicorn veya benzeri servislerle Unix socket üzerinden haberleşebilir. Socket mevcut olsa bile Nginx worker kullanıcısının gerekli erişim izni bulunmayabilir.

İzinleri incelemeden herkese yazma yetkisi vermek hatayı geçici olarak gizleyebilir, fakat ciddi bir güvenlik problemi oluşturabilir.

• Socket sahibi ve grubu
• Dosya ve üst dizin izinleri
• Nginx worker kullanıcısı
• Uygulamanın socket oluşturma ayarları

Kaynak yetersizliği

Backend çalışıyor görünse bile CPU, bellek, disk veya bağlantı limitleri nedeniyle isteklere cevap veremeyebilir.

Bu durumda timeout değerlerini artırmak problemi çözmek yerine kullanıcıların daha uzun süre beklemesine neden olabilir.

• OOM ve bellek baskısı
• Dolu disk veya inode alanı
• Aşırı CPU kullanımı
• Tükenen veritabanı connection pool’u
• Yetersiz worker sayısı
• Dosya tanımlayıcı limitleri

502 ile 504 arasındaki fark

502 Bad Gateway, Nginx’in upstream servisten geçerli bir cevap alamadığını; 504 Gateway Timeout ise upstream servisin beklenen süre içinde cevap vermediğini ifade eder.

Gerçek kök neden yalnız HTTP durum koduna bakılarak belirlenemez. Nginx error logu, uygulama logu ve olay zaman çizelgesi birlikte incelenmelidir.

Güvenli ilk kontroller

Production ortamında değişiklik yapmadan önce hatanın kapsamı, başlangıç zamanı ve son değişikliklerle ilişkisi belirlenmelidir.

• Hata bütün URL’lerde mi, belirli bir endpoint’te mi?
• Backend beklenen IP ve portu dinliyor mu?
• Nginx’in bulunduğu ortamdan backend’e erişilebiliyor mu?
• Hata deployment sonrasında mı başladı?
• Nginx ve uygulama logları aynı zaman aralığında ne söylüyor?
• CPU, bellek, disk veya bağlantı baskısı var mı?
• Sorun sürekli mi, yalnız yoğun trafik altında mı oluşuyor?

Kaçınılması gereken müdahaleler

Kanıt toplanmadan yapılan müdahaleler kök nedeni gizleyebilir veya kesintiyi büyütebilir.

• Nginx’i sürekli yeniden başlatmak
• Bütün timeout değerlerini artırmak
• Socket izinlerini kontrolsüz biçimde açmak
• Firewall’u tamamen kapatmak
• Container ve volume’leri silmek
• Logları almadan deployment’ı geri çevirmek

Ne zaman uzman desteği alınmalı?

Hata aralıklı tekrarlanıyorsa, birden fazla servis etkileniyorsa veya müdahalenin kesinti ve veri kaybı riski bulunuyorsa sorun yalnızca bir Nginx ayarı olarak değerlendirilmemelidir.

Nginx, uygulama, container ağı, veritabanı ve sistem kaynaklarının aynı zaman çizelgesinde incelenmesi kalıcı çözüm için gereklidir.