Nginx 502 Bad Gateway Hatası Nasıl Çözülür? Nedenleri ve Çözümleri

Nginx 502 Bad Gateway hatası, Nginx'in reverse proxy olarak iletişim kurduğu backend uygulamasından geçerli bir yanıt alamadığını gösterir. Node.js ve PM2 kullanılan sunucularda en sık nedenler uygulamanın durmuş olması, yanlış porta proxy yapılması, uygulamanın sürekli çökmesi veya Nginx'in backend'e bağlanamamasıdır.

Örneğin yapı:

Kullanıcı → Nginx → Node.js uygulaması

şeklindeyse ve Nginx çalışıyor ancak Node.js uygulamasına ulaşamıyorsa kullanıcı karşısında:

502 Bad Gateway

hatası görebilir.

1. Önce uygulamanın çalışıp çalışmadığını kontrol edin

PM2 kullanıyorsanız:

pm2 status

veya:

pm2 list

komutunu çalıştırın.

Uygulamanızın durumu:

online

olmalıdır.

Eğer:

- stopped

- errored

- launching

gibi bir durum görüyorsanız önce uygulamanın neden çalışmadığını araştırın.

2. PM2 loglarını kontrol edin

Uygulama sürekli kapanıyorsa:

pm2 logs

komutunu kullanabilirsiniz.

Belirli bir uygulama için:

pm2 logs uygulama-adi

kullanılabilir.

Burada örneğin:

- Veritabanı bağlantı hatası

- Eksik environment değişkeni

- Port çakışması

- JavaScript hatası

- Dosya bulunamadı hatası

- Permission hatası

görülebilir.

502 hatasının gerçek nedeni çoğu zaman Nginx'ten ziyade backend uygulamasında bulunur.

3. Backend portunu kontrol edin

Node.js uygulamanız örneğin:

127.0.0.1:3000

üzerinde çalışıyorsa Nginx'in de aynı hedefe proxy yapması gerekir.

Nginx yapılandırmasında örneğin:

proxy_pass http://127.0.0.1:3000;

bulunabilir.

Ancak uygulama gerçekte:

4000

portunda çalışıyorsa Nginx yanlış porta istek gönderdiği için bağlantı başarısız olur.

Uygulamanın hangi portu dinlediğini kontrol edin.

4. Backend'e doğrudan istek gönderin

Nginx'i devre dışı bırakarak backend'in kendisini test etmek sorunun hangi katmanda olduğunu anlamayı kolaylaştırır.

Örneğin uygulama 3000 portundaysa sunucunun kendi terminalinden:

curl http://127.0.0.1:3000

çalıştırabilirsiniz.

Uygulama cevap veriyorsa backend ayaktadır.

Cevap alınamıyorsa sorun büyük ihtimalle Node.js uygulaması, port veya servis tarafındadır.

Bu yöntem:

Nginx mi sorunlu, uygulama mı sorunlu?

sorusunu hızlı şekilde ayırmaya yardımcı olur.

5. Port gerçekten dinleniyor mu kontrol edin

Sunucuda dinlenen portları görmek için:

ss -lntp

kullanılabilir.

Belirli bir port için:

ss -lntp | grep 3000

çalıştırabilirsiniz.

Hiçbir sonuç görünmüyorsa uygulama beklediğiniz portu dinlemiyor olabilir.

6. Nginx yapılandırmasını kontrol edin

Yapılandırmada değişiklik yaptıysanız:

sudo nginx -t

komutunu çalıştırın.

Başarılı yapılandırmada syntax kontrolünün başarılı olduğuna ilişkin mesaj görmelisiniz.

Hata varsa Nginx'i yeniden yüklemeden önce yapılandırmayı düzeltin.

Doğrulama başarılı olduktan sonra uygun sistemlerde:

sudo systemctl reload nginx

kullanılabilir.

reload, çalışan bağlantıları gereksiz yere kesmeden yeni yapılandırmanın yüklenmesi açısından çoğu yapılandırma değişikliğinde tercih edilebilir.

7. Nginx error.log dosyasını kontrol edin

502 hatasında en önemli kaynaklardan biri Nginx hata logudur.

Genellikle:

/var/log/nginx/error.log

altında bulunur.

Son kayıtları görmek için:

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

kullanabilirsiniz.

Canlı takip için:

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

kullanılabilir.

Örneğin:

connect() failed (111: Connection refused) while connecting to upstream

benzeri bir mesaj görüyorsanız Nginx backend'e bağlanamıyor olabilir.

Bu durumda port ve uygulama durumu kontrol edilmelidir.

8. Connection refused ne anlama gelir?

Nginx logunda upstream için Connection refused görüyorsanız çoğunlukla hedef IP ve port üzerinde bağlantıyı kabul eden bir servis bulunmamaktadır.

Örneğin Nginx:

127.0.0.1:3000

adresine bağlanmaya çalışıyor ancak Node.js durmuşsa 502 oluşabilir.

Kontrol edin:

pm2 status

ss -lntp | grep 3000

curl http://127.0.0.1:3000

Bu üç kontrol sorunun kaynağını hızlıca daraltabilir.

9. Uygulama sürekli restart oluyorsa

PM2 üzerinde uygulamanın restart sayısı sürekli artıyorsa backend kararlı çalışmıyor olabilir.

Kontrol için:

pm2 describe uygulama-adi

ve:

pm2 logs uygulama-adi

kullanabilirsiniz.

Sürekli yeniden başlama nedenleri arasında:

- Uygulama hataları

- Veritabanı bağlantısının başarısız olması

- Eksik environment değişkenleri

- Bellek problemleri

- Port çakışması

- Başlangıç sırasında oluşan exception

bulunabilir.

Sadece:

pm2 restart

çalıştırmak asıl hatayı çözmeyebilir.

10. Environment değişkenlerini kontrol edin

Uygulamanız:

- DATABASE_URL

- PORT

- API anahtarları

- Session secret

gibi environment değişkenlerine ihtiyaç duyabilir.

Terminalde manuel başlatıldığında çalışan uygulama PM2 üzerinden başlatıldığında farklı environment kullanıyorsa hata verebilir.

PM2 yapılandırmasını ve uygulamanın environment yönetimini kontrol edin.

Hassas değerleri loglarda veya herkese açık dosyalarda paylaşmayın.

11. Veritabanı bağlantısı 502 oluşturabilir mi?

Dolaylı olarak evet.

Örneğin Node.js uygulaması PostgreSQL'e bağlanamadığında tamamen kapanıyorsa:

Nginx → Node.js

bağlantısı artık kurulamaz.

Sonuçta kullanıcı 502 görebilir.

Bu durumda:

systemctl status postgresql

gibi uygun servis kontrolü yapılabilir.

Ancak veritabanının çalışıyor olması uygulamanın doğru bağlantı bilgilerine sahip olduğunu garanti etmez.

PM2 logları burada önemlidir.

12. Uygulamanın hangi IP adresini dinlediğini kontrol edin

Uygulama:

127.0.0.1

veya:

0.0.0.0

üzerinde dinleyebilir.

Nginx'in proxy_pass hedefiyle uygulamanın dinlediği adresin uyumlu olması gerekir.

Aynı sunucudaki Node.js uygulamasına reverse proxy yapılıyorsa localhost üzerinden bağlantı yaygın bir yöntemdir.

Backend portunu gereksiz yere internete açmak yerine yalnızca yerel bağlantıya izin vermek güvenlik açısından daha uygun olabilir.

13. Unix socket kullanılıyorsa izinleri kontrol edin

Nginx backend'e TCP portu yerine Unix socket üzerinden bağlanıyorsa socket dosyasının:

- Var olması

- Doğru konumda bulunması

- Nginx tarafından erişilebilir olması

gerekir.

Yanlış socket yolu veya permission problemi de upstream bağlantısının başarısız olmasına neden olabilir.

14. Firewall 502 hatasına neden olabilir mi?

Nginx ile backend aynı sunucudaysa ve localhost kullanılıyorsa genellikle dış firewall kurallarından farklı bir durum söz konusudur.

Ancak backend başka bir sunucudaysa:

- Firewall

- Security group

- Ağ kuralları

- Backend'in dinlediği IP

kontrol edilmelidir.

Güvenlik duvarını tamamen kapatmak yerine yalnızca gerekli bağlantının doğru şekilde izinli olduğundan emin olun.

15. 502 ile 504 arasındaki fark nedir?

Bu iki hata karıştırılabilir.

502 Bad Gateway:

Nginx upstream'den geçerli yanıt alamamıştır veya bağlantı kurulmasında sorun yaşanmıştır.

504 Gateway Timeout:

Nginx upstream'den gerekli yanıtı beklemiş ancak zaman aşımına uğramıştır.

Örneğin backend tamamen kapalıysa 502 görülebilir.

Backend çalışıyor ancak bir işlem çok uzun sürüyorsa 504 görülebilir.

Gerçek nedeni belirlemek için loglara bakılmalıdır.

16. Nginx'i restart etmek 502'yi çözer mi?

Bazen yapılandırma değişikliğinin uygulanmasını sağlayabilir ancak 502'nin asıl nedeni backend uygulamasının kapalı olmasıysa Nginx'i yeniden başlatmak sorunu çözmez.

Önce:

sudo nginx -t

ardından gerekiyorsa:

sudo systemctl reload nginx

kullanılabilir.

Sorunu anlamadan sürekli Nginx restart yapmak doğru hata ayıklama yöntemi değildir.

17. PM2 restart etmek yeterli mi?

Uygulama geçici olarak durmuşsa:

pm2 restart uygulama-adi

uygulamayı tekrar çalıştırabilir.

Ancak uygulama birkaç saniye sonra yeniden çöküyorsa logları incelemek gerekir.

Şu döngü:

başlat → çök → PM2 restart → tekrar çök

devam ederken kullanıcılar 502 hatası görebilir.

Asıl uygulama hatası düzeltilmelidir.

18. Sunucu yeniden başladıktan sonra 502 oluşuyorsa

Reboot sonrasında:

- Nginx başlamış

- Node.js uygulaması başlamamış

olabilir.

Bu durumda Nginx gelen isteği backend'e gönderir ancak bağlantı kuramaz.

PM2 için:

pm2 startup

ve:

pm2 save

yapılandırmasının doğru olduğundan emin olun.

Reboot sonrasında:

pm2 list

ile uygulamanın otomatik başladığını doğrulayın.

19. Disk doluluğunu kontrol edin

Diskin tamamen dolması uygulama ve servislerde beklenmeyen hatalara neden olabilir.

Kontrol etmek için:

df -h

kullanın.

Disk kritik seviyedeyse:

- Loglar

- Eski yedekler

- Cache

- Upload dosyaları

kontrol edilmelidir.

Ancak disk açmak için sistem veya veritabanı dosyalarını rastgele silmeyin.

20. RAM durumunu kontrol edin

Uygulama bellek yetersizliği nedeniyle kapanıyorsa 502 ortaya çıkabilir.

Temel kontrol için:

free -h

kullanabilirsiniz.

Process'leri incelemek için:

top

veya sisteminizde kuruluysa:

htop

kullanılabilir.

Kernel tarafından bir process'in bellek nedeniyle sonlandırıldığından şüpheleniyorsanız sistem logları da incelenmelidir.

502 hatası için hızlı kontrol sırası

Bir Node.js + PM2 + Nginx sunucusunda 502 görüyorsanız şu sırayla ilerleyebilirsiniz:

1. pm2 status

2. pm2 logs uygulama-adi

3. ss -lntp

4. curl http://127.0.0.1:PORT

5. Nginx proxy_pass hedefini kontrol edin.

6. sudo nginx -t

7. /var/log/nginx/error.log dosyasını inceleyin.

8. df -h ile disk alanını kontrol edin.

9. free -h ile RAM durumuna bakın.

10. Veritabanı gibi bağımlı servisleri kontrol edin.

Bu sıra genellikle sorunun hangi katmanda olduğunu hızlı şekilde belirlemeye yardımcı olur.

Sık yapılan hatalar

Nginx 502 sorununda sık yapılan yanlışlar:

- Loglara bakmadan sürekli Nginx restart etmek

- PM2 online durumunu görüp backend'i ayrıca test etmemek

- Yanlış proxy_pass portu kullanmak

- Environment değişkenlerini unutmak

- Uygulamanın restart loop'a girdiğini fark etmemek

- Firewall'u tamamen kapatmak

- Nginx yapılandırmasını nginx -t yapmadan uygulamak

- Veritabanı sorununu Nginx sorunu sanmak

Özetle, Nginx 502 Bad Gateway hatasında ilk kontrol edilmesi gereken yer çoğu zaman Nginx'in arkasında çalışan backend uygulamasıdır. PM2 durumunu ve loglarını kontrol edin, backend portuna doğrudan istek gönderin ve ardından Nginx proxy_pass yapılandırmasını inceleyin.

Node.js + PM2 + Nginx yapısında en etkili teşhis yöntemi, sistemi Nginx → backend → veritabanı ve diğer bağımlılıklar şeklinde katmanlara ayırarak hangi noktada bağlantının koptuğunu bulmaktır.