Nginx 502 Bad Gateway hatası nasıl çözülür?

Nginx 502 Bad Gateway hatasında upstream servisi, host ve portu, timeout kayıtlarını, Unix socket izinlerini ve Docker ağını doğru sırayla kontrol edin.

Nginx 502 Bad Gateway hatası, Nginx’in reverse proxy veya gateway olarak bağlandığı upstream uygulamadan geçerli bir yanıt alamadığını gösterir. Sorun çoğu zaman Nginx’in kendisinden değil; kapalı servis, yanlış host/port, ağ erişimi, socket izni veya uygulamanın bağlantıyı erken kapatmasından kaynaklanır.

Bu nedenle ilk refleks olarak timeout değerlerini büyütmek doğru değildir. Nginx error log’undaki mesajı, aynı anda upstream servisin durumuyla eşleştirmek çok daha hızlı sonuç verir.

1. Error log’daki asıl nedeni okuyun

Hatanın oluştuğu saniyeyi not alın ve ilgili error log’u inceleyin:

sudo tail -n 100 /var/log/nginx/error.log
sudo journalctl -u nginx --since "10 minutes ago"

connect() failed (111: Connection refused) genellikle hedef portta dinleyen servis olmadığını veya yanlış adrese gidildiğini anlatır. upstream timed out, bağlantının kurulduğunu fakat beklenen sürede yanıt alınamadığını gösterir. upstream prematurely closed connection ise uygulamanın yanıtı tamamlamadan bağlantıyı kapattığına işaret eder.

2. Upstream servisin gerçekten dinlediğini doğrulayın

sudo systemctl status my-app
sudo ss -lntp
curl -v http://127.0.0.1:3000/health

Health endpoint’ini mümkünse Nginx’in çalıştığı aynı sunucu veya konteyner ağından çağırın. Uygulama yalnızca 127.0.0.1 üzerinde dinliyorsa başka bir konteynerden erişilemez. Uygulama 0.0.0.0 üzerinde dinliyor fakat güvenlik duvarı trafiği kesiyorsa doğrudan curl testi bunu ayırmaya yardım eder.

3. Etkin proxy_pass ayarını görün

sudo nginx -T
sudo nginx -t

nginx -T, include edilen dosyalarla birlikte etkin yapılandırmayı gösterir. Çıktıda parola veya özel başlık bulunabileceği için herkese açık paylaşmayın. İsteğin eşleştiği server ve location bloğunda proxy_pass hedefini kontrol edin:

location /api/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Host, port ve protokol uygulamayla aynı olmalıdır. HTTPS bekleyen bir upstream’e HTTP ile gitmek veya proxy_pass sonundaki eğik çizgiyi bilinçsizce değiştirmek farklı sorunlar doğurabilir.

4. Docker ağında localhost yanılgısına dikkat edin

Nginx ayrı bir konteynerdeyse 127.0.0.1 Nginx konteynerinin kendisidir; uygulama konteyneri değildir. Aynı Compose ağı içindeki servis adını ve uygulamanın konteyner portunu kullanın:

upstream backend {
    server api:3000;
}

location /api/ {
    proxy_pass http://backend;
}

Nginx konteynerinden curl http://api:3000/health çalıştırarak DNS ve ağ erişimini birlikte test edin. Host’a yayımlanan port ile konteyner içi portu karıştırmayın.

5. Unix socket izinlerini ve güvenlik katmanlarını kontrol edin

PHP-FPM, Gunicorn veya benzeri bir servis Unix socket kullanıyorsa Nginx kullanıcısının socket’e erişebilmesi gerekir. Socket yolu iki config’te aynı olmalı; dosyanın sahibi, grubu ve dizin geçiş izinleri uygun olmalıdır. SELinux etkin sistemlerde doğru Unix izinleri bulunsa bile politika erişimi engelleyebilir. Log’da Permission denied görmeden rastgele izin açmayın.

6. Timeout’u ancak ölçümden sonra değiştirin

Uygulama işlemi gerçekten uzun sürüyorsa ve log’da upstream timed out varsa proxy_connect_timeout ile proxy_read_timeout arasındaki farkı gözetin. Connect timeout bağlantı kurulmasını, read timeout iki okuma arasındaki beklemeyi sınırlar. Önce yavaş sorguyu, harici servis beklemesini veya uygulama çökmesini düzeltin; sonra ihtiyaç varsa ölçülü bir değer belirleyin.

location /report/ {
    proxy_pass http://backend;
    proxy_connect_timeout 5s;
    proxy_read_timeout 60s;
}

Değişiklikten sonra nginx -t çalıştırın ve başarılıysa servisi kendi dağıtım yönteminize göre reload edin. Ardından aynı isteği tekrar üretip Nginx ve uygulama log’unu birlikte izleyin.