502 Bad Gateway Hatası Nedir ve Nasıl Çözülür?

502 Bad Gateway hatası nedir?

502 Bad Gateway, bir web sunucusunun veya reverse proxy’nin arka uç sunucusundan kullanılabilir bir HTTP yanıtı alamadığını gösterir. İstemci isteği proxy’ye ulaşır; kopukluk çoğunlukla Nginx, Apache, CDN, PHP-FPM, uygulama sunucusu ya da bu bileşenler arasındaki iletişimde çıkar.

Tarayıcıda gördüğünüz 502 sayfası, sorunun bilgisayarınızda olduğu anlamına gelmez. İstek Nginx gibi dışarıdan görünen sunucuya kadar gelmiş olabilir; fakat Nginx’in bağlanmaya çalıştığı upstream yanıt vermiyor, bağlantıyı kapatıyor veya beklenen biçimde cevap üretemiyordur.

HTTP durum kodlarının tanımı RFC 9110’da yer alır. 502, gateway ya da proxy görevi yapan sunucunun upstream’den geçersiz bir yanıt aldığını ifade eder. MDN de kodu istemci ile hedef uygulama arasındaki geçiş katmanında oluşan bir sunucu yanıtı olarak açıklar.

502 hatasının arkasında hangi sorunlar vardır?

Bir reverse proxy ile uygulama sunucusu arasında birkaç ayrı süreç çalışır. Kullanıcı Nginx’e bağlanır, Nginx PHP-FPM’e veya Node.js uygulamasına istek iletir, uygulama da veritabanından ya da başka bir servisten veri alır. Zincirin tek bir halkası koptuğunda dışarıya 502 görünebilir.

• Upstream servis çalışmıyordur: PHP-FPM, Gunicorn, uWSGI, Node.js veya Docker konteyneri durmuş olabilir.
• Yanlış socket ya da port tanımlanmıştır: Nginx 127.0.0.1:3000 adresine bakarken uygulama başka bir portta dinliyor olabilir.
• Unix socket erişimi yoktur: Socket dosyasının sahibi, grubu veya izinleri Nginx kullanıcısının erişimine uygun değildir.
• Upstream zaman aşımına uğramıştır: Uygulama ağır bir sorgu çalıştırıyor, kilitleniyor ya da isteği verilen sürede tamamlayamıyordur.
• Uygulama geçersiz HTTP yanıtı üretmiştir: Yanıt başlıkları bozuk olabilir veya uygulama bağlantıyı cevap vermeden kapatabilir.
• Kaynak yetersizliği vardır: RAM tükenmesi, OOM killer, CPU baskısı, disk doluluğu veya dosya tanıtıcısı sınırı süreçleri etkileyebilir.
• Proxy katmanları uyuşmuyordur: CDN, load balancer, Nginx ve uygulama sunucusunun timeout ya da bağlantı ayarları birbirini tutmayabilir.

502 gördüğünüzde doğrudan Nginx’i yeniden başlatmak iyi bir teşhis yöntemi değildir. Servis yeniden başladıktan sonra sayfa açılabilir; fakat kök neden hâlâ oradadır. Loglar konuşmadan terminaldeki restart düğmesine basmak, benim pek sevdiğim bir yöntem değil.

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

İlk iş, hatayı hangi katmanın ürettiğini ayırmaktır. Alan adı CDN üzerinden geçiyorsa CDN panelindeki hata mesajı ile origin sunucunun mesajı aynı olmayabilir. Ben önce isteği yerel origin’e, sonra dış proxy üzerinden kontrol ederim.

1. Servislerin durumunu kontrol edin

Önce web sunucusunu ve arka uç servisini listeleyin. Dağıtıma göre servis adı değişebilir; Ubuntu ve Debian’da PHP sürümünün komut içinde doğru olması gerekir.

sudo systemctl status nginx --no-pager
sudo systemctl status php8.2-fpm --no-pager
sudo ss -ltnp | grep -E ':(80|443|3000|8000)'

systemctl status çıktısında yalnızca active satırına bakmayın. Son başlatma zamanı, ana süreç PID’si ve son log satırları da değerlidir. ss çıktısı uygulamanın gerçekten beklediğiniz portu dinleyip dinlemediğini gösterir.

Servis durmuşsa önce logları inceleyin, ardından kontrollü biçimde başlatın:

sudo journalctl -u php8.2-fpm --since '30 minutes ago' --no-pager
sudo systemctl restart php8.2-fpm
sudo systemctl status php8.2-fpm --no-pager

Buradaki restart teşhisin yerine geçmez. Yeniden başladıktan sonra hata kaybolsa bile önceki loglarda bellek, yapılandırma veya uygulama çökmesi izini arayın.

2. Nginx veya Apache hata loglarını okuyun

Nginx için yaygın hata logu yolu /var/log/nginx/error.log dosyasıdır. Sanal host özelinde farklı bir dosya tanımlanmış olabilir. Apache’de çoğu Debian kurulumunda /var/log/apache2/error.log kullanılır.

sudo tail -n 80 /var/log/nginx/error.log
sudo journalctl -u nginx --since '15 minutes ago' --no-pager
sudo nginx -t

connect() failed, Nginx’in upstream’e bağlanamadığını; upstream timed out, bağlantı veya yanıt için bekleme süresinin aşıldığını; permission denied ise çoğunlukla Unix socket ya da dosya izinlerini incelemeniz gerektiğini gösterir.

nginx -t yapılandırma sözdizimini kontrol eder. Komut başarılı olsa bile upstream uygulamasının çalıştığını kanıtlamaz; yalnızca Nginx dosyalarının okunabilir ve sözdiziminin geçerli olduğunu söyler.

3. Upstream servisine proxy’yi atlayarak bağlanın

Uygulama TCP portunda çalışıyorsa doğrudan istek gönderin:

curl -i --max-time 10 http://127.0.0.1:3000/health
curl -i --max-time 10 http://127.0.0.1:8000/

Uygulama Unix socket kullanıyorsa Nginx yapılandırmasındaki socket yolunu doğrulayın. PHP-FPM için birçok Debian kurulumunda yol, sürüme göre /run/php/php8.2-fpm.sock biçimindedir.

grep -R 'fastcgi_pass
a' /etc/nginx/sites-enabled/ /etc/nginx/conf.d/ 2>/dev/null
sudo ls -l /run/php/

Yukarıdaki ilk komutta satır sonu nedeniyle sorun yaşamamak için gerçek kullanımda deseni tek satır yazın:

grep -R -E 'fastcgi_pass|proxy_pass' /etc/nginx/sites-enabled/ /etc/nginx/conf.d/ 2>/dev/null

Porta doğrudan istek beklenen durum kodunu döndürürken alan adında 502 görüyorsanız sorun büyük ihtimalle proxy yapılandırması, socket izinleri, TLS veya timeout tarafındadır. Doğrudan istek de başarısızsa Nginx’i kurcalamadan uygulama servisine dönün.

4. Socket izinlerini ve kullanıcıları karşılaştırın

FastCGI socket’i genellikle PHP-FPM tarafından oluşturulur. Nginx worker süreci ise www-data gibi farklı bir kullanıcıyla çalışabilir. Socket’in grup sahibi ve grup erişimi uyuşmuyorsa Nginx upstream’e bağlanamaz.

ps -o user,group,cmd -C nginx
sudo stat /run/php/php8.2-fpm.sock
sudo grep -E '^(listen|listen.owner|listen.group|listen.mode)' /etc/php/8.2/fpm/pool.d/www.conf

İzin sorunu gördüğünüzde ilk refleksiniz chmod 777 olmasın. Bu komut erişim modelini düzeltmez, yalnızca gereğinden fazla yetki verir. PHP-FPM pool ayarındaki listen.group ile Nginx kullanıcısının grubu uyumlu olmalı; değişiklikten sonra yapılandırma doğrulanıp servis kontrollü şekilde yeniden yüklenmelidir.

5. Timeout ve kaynak kullanımını inceleyin

Bir sorgu 60 saniye sürüyorsa proxy timeout değerini rastgele yükseltmek yerine sorgunun neden yavaş olduğunu bulun. Disk doluluğu, swap kullanımı ve RAM baskısı da 502’nin dolaylı nedenleri olabilir.

free -h
df -h
sudo dmesg -T | grep -iE 'oom|killed process|out of memory'
htop

df -h toplam disk kullanımını gösterir; hangi dizinin alanı tükettiğini görmek için ncdu daha kullanışlıdır. Benim bir deploy sırasında yaşadığım 502 vakasında sorun uygulama kodu değil, staging sanılan production sunucusuna yazılan hatalı Nginx yapılandırmasıydı. Kırmızı production prompt’u o günden sonra pazarlık konusu olmaktan çıktı. Önce nginx -t, sonra reload.

Kernel loglarında OOM kaydı varsa uygulama işlemi Linux tarafından öldürülmüş olabilir. Böyle bir durumda Nginx timeout değerini artırmak işe yaramaz; PHP-FPM worker sayısı, uygulama belleği, swap ve VPS kaynakları birlikte değerlendirilmelidir.

Nginx, Apache ve uygulama loglarında ne aranır?

Her katmanın farklı bir soruya cevabı vardır: Nginx isteği aldı mı, upstream’e bağlandı mı, uygulama isteği işledi mi, veritabanı cevap verdi mi? Aynı zaman aralığını kullanarak logları yan yana incelemek teşhisi hızlandırır.

Bir log satırını tek başına yorumlamayın. Uygulamada görülen 500 ile Nginx’in kullanıcıya gösterdiği 502 farklı katmanları işaret eder. Uygulama HTTP 500 üretmiş olabilir; Nginx ise uygulamaya hiç bağlanamadığında 502 döndürür.

502 ile 500, 504 ve 503 arasındaki fark nedir?

Bu kodlar birbirine benzese de müdahale noktası değişir. Hata sayfasına bakıp yanlış servisi yeniden başlatmamak için ayrımı net tutmak gerekir.

Gerçek sistemlerde bu kodlar tamamen birbirinden kopuk değildir. PHP-FPM havuzu kaynak sınırına ulaştığında 502, uzun süren bir backend işlemi için ise 504 görebilirsiniz. Nginx’teki proxy_connect_timeout, proxy_read_timeout ve FastCGI timeout ayarlarının neyi beklediğini ayırmadan değerleri büyütmek, sorunu yalnızca daha geç görünür hâle getirir.

Docker ve reverse proxy arkasında 502 nasıl çözülür?

Docker kullanan sunucularda sık karşılaştığım hata, konteyner portu ile host portunun karıştırılmasıdır. Aynı Docker ağına bağlı Nginx çoğu durumda host’un yayınladığı portu değil, servis adını ve konteynerin dinlediği portu kullanmalıdır.

docker compose ps
docker compose logs --tail=100 app
docker inspect app --format '{{json .NetworkSettings.Networks}}'

Uygulama konteyner içinde 3000 portunda dinliyorsa Nginx’in proxy_pass http://app:3000; kullanması gerekebilir. Uygulama yalnızca 127.0.0.1 üzerinde dinliyorsa konteyner ağından gelen bağlantıları kabul etmeyebilir; bind adresini de kontrol edin.

Docker ile yeni çalışıyorsanız VPS’te Docker Kurulumu ve İlk Konteyneri Çalıştırma yazısındaki ağ ve servis kontrolleri işinize yarar. Konteynerin çalışıyor görünmesi, uygulamanın sağlıklı olduğu anlamına gelmez; healthcheck, uygulama logu ve aynı ağdan yapılan curl testi birlikte değerlendirilmelidir.

docker compose exec nginx getent hosts app
docker compose exec nginx curl -i --max-time 5 http://app:3000/health

İlk komut servis adının çözümlendiğini, ikinci komut ise Nginx konteynerinin uygulamaya gerçekten erişebildiğini test eder. DNS çözülüyor fakat bağlantı kurulamıyorsa port veya bind adresi yanlış olabilir.

CDN kullanırken 502 hatası neden görülür?

CDN, tarayıcı ile origin sunucu arasına bir katman daha ekler. Tarayıcı CDN’e, CDN de sizin sunucunuza bağlanır. Origin kapalıysa, yalnızca belirli IP’lerden erişilebiliyorsa, TLS ayarı uyuşmuyorsa veya firewall CDN adreslerini engelliyorsa CDN kendi 502 sayfasını gösterebilir.

Kontrol sırası şöyle olabilir:

1. Origin sunucunun IP adresine, uygun Host başlığıyla yerelden istek gönderin.
2. CDN panelinde origin health check ve hata zamanını kontrol edin.
3. Web sunucusunun erişim logunda CDN isteğinin görünüp görünmediğine bakın.
4. Origin firewall’ının CDN IP aralıklarını engellemediğini doğrulayın.
5. Origin sertifikasının CDN’in seçtiği TLS moduyla uyumlu olduğunu kontrol edin.

Alan adının DNS ve proxy davranışını anlamak için Proxy Nedir? Proxy Sunucu Ne İşe Yarar? başlıklı yazı yardımcı olacaktır. Tarayıcınızın DNS çözümlemesi başarılı olabilir; CDN’in origin’e yaptığı bağlantı yine de başarısız kalabilir.

Yönetici değil, ziyaretçiyseniz ne yapabilirsiniz?

Bir web sitesinde 502 görüyorsanız sayfayı birkaç dakika sonra yenileyin ve mümkünse farklı bir ağdan deneyin. Sürekli yenilemek sunucunun üzerindeki yükü artırabilir. Hata yalnızca tek sitede görülüyor, başka siteler açılıyorsa sorun büyük ihtimalle site tarafındadır.

Site sahibiyseniz destek talebine şu bilgileri ekleyin:

• Hatanın görüldüğü tam URL ve saat bilgisi
• Hatanın tüm sayfalarda mı, yalnızca tek endpoint’te mi oluştuğu
• Tarayıcı, mobil uygulama veya API istemcisi bilgisi
• Varsa request ID, CDN Ray ID veya sunucu logundaki zaman damgası
• Yakın zamanda yapılan deploy, DNS, SSL, firewall veya PHP sürümü değişiklikleri

İstemci tarafında DNS temizlemek veya tarayıcı önbelleğini silmek, durmuş bir upstream’i düzeltmez. Bu adımlar eski bir proxy yanıtından ya da yerel çözümleme probleminden şüpheleniyorsanız anlamlıdır.

502 hatasını önlemek için hangi kontroller yapılmalı?

Hata çıktıktan sonra müdahale etmek kadar, oluşmadan önce sinyal üretmek de değerlidir. Benim kurduğum temel izleme düzeninde web isteği, uygulama servisi, kaynak kullanımı ve loglar ayrı ayrı gözlenir.

• Health endpoint: Uygulamanın yalnızca portu dinlediğini değil, temel bağımlılıklarıyla cevap verebildiğini test edin.
• Servis izleme: PHP-FPM, Node.js, Docker ve Nginx durumlarını monitoring’e ekleyin.
• Log rotasyonu: /var alanının dolmasını beklemeden disk kullanım alarmı koyun.
• Kaynak takibi: RAM, swap, CPU, disk I/O ve dosya sistemi doluluğunu birlikte izleyin.
• Timeout tasarımı: CDN, load balancer, Nginx ve uygulama timeout değerlerini bilinçli bir sıraya koyun.
• Dağıtım kontrolü: Yeni sürümü doğrudan production’a göndermek yerine healthcheck ve geri dönüş planı kullanın.
• Yapılandırma testi: Nginx için nginx -t, Docker Compose için yapılandırma doğrulaması çalıştırın.

Bir sunucuda yalnızca uptime grafiğine bakmak yetmez. Uptime yüksekken PHP-FPM havuzu dolabilir; Nginx ayakta olduğu için genel monitoring yeşil kalırken ziyaretçiler 502 görebilir. Sentetik HTTP kontrolleri bu ayrımı yakalar.

Benim sık yaptığım küçük hata, deploy sonrasında yalnızca ana sayfayı kontrol etmekti. Sağlık endpoint’i 200 dönerken veritabanı kullanan gerçek sayfada upstream timeout oluşmuştu. Şimdi hem basit healthcheck hem de veritabanına dokunan düşük maliyetli bir sentetik istek izliyorum.

Sık Sorulan Sorular

502 Bad Gateway hatası genellikle kimden kaynaklanır?

Çoğunlukla reverse proxy ile arka uç uygulaması arasındaki iletişimden kaynaklanır. Uygulamanın çökmesi, yanlış port, socket izni, kaynak yetersizliği veya CDN-origin bağlantısı da aynı kodu üretebilir.

502 hatası hosting firması tarafından mı çözülür?

Paylaşımlı hosting kullanıyorsanız PHP-FPM veya web sunucusu katmanına erişiminiz olmayabilir; hosting desteği servis ve sunucu loglarını incelemelidir. Kendi VPS’inizde ise Nginx, uygulama servisi, firewall ve kaynak kullanımını sizin kontrol etmeniz gerekir.

502 hatasını düzeltmek için Nginx yeniden başlatılır mı?

Yapılandırma değişikliğinden sonra kontrollü reload veya restart gerekebilir; fakat önce error.log ve upstream servis durumu incelenmelidir. Log okumadan yeniden başlatmak geçici bir düzelme sağlasa bile gerçek nedeni saklayabilir.

502 ile 504 arasındaki temel fark nedir?

502, proxy’nin upstream’den geçersiz veya kullanılamayan bir yanıt aldığını; 504 ise upstream’den zamanında yanıt alamadığını anlatır. İki durumda da uygulama, ağ bağlantısı ve proxy logları kontrol edilir. 504’te yavaş sorgu ve timeout incelemesi daha öne çıkar.

Ben 502 gördüğümde ilk olarak servisi değil yolu izliyorum: istemci, proxy, socket veya port, uygulama ve en son bağımlılıklar. Hangi halkada cevap kesiliyorsa müdahale de orada başlıyor.

Kaynaklar

• RFC 9110 – 502 Bad Gateway — rfc-editor.org
• MDN – 502 Bad Gateway — developer.mozilla.org
• NGINX – HTTP Proxy Module — nginx.org
• Docker Docs – Networking in Compose — docs.docker.com