502 Bad Gateway Hatası: Hosting ve Sunucularda Tanılama Rehberi

Son Güncelleme: Eylül 2026

502 Bad Gateway hatası, bir web isteğini ileten sunucunun arka uç uygulamadan beklediği geçerli yanıtı alamadığını gösterir. Bu rehberde hatanın ne anlama geldiğini, Nginx ve PHP-FPM gibi bileşenlerde nerede aranacağını ve hizmeti güvenli biçimde geri getirmek için hangi kontrollerin yapılacağını öğrenebilirsiniz.

İçindekiler

• 502 Bad Gateway Nedir?
• 502, 500, 503 ve 504 Arasındaki Farklar
• İstek Zincirinde Hata Nerede Oluşur?
• 502 Hatasının Yaygın Nedenleri
• İlk Kontroller ve Tanılama Sırası
• Nginx ve Arka Uç Bağlantısını İnceleme
• PHP-FPM Kaynaklı Sorunları İnceleme
• Tekrarlayan 502 Hatalarını Önleme
• Sıkça Sorulan Sorular
• Sonuç

502 Bad Gateway Nedir?

HTTP 502, ağ geçidi veya ters vekil (reverse proxy) olarak çalışan bir sunucunun üst sunucudan (upstream) geçerli bir yanıt alamadığında döndürebildiği sunucu hata kodudur. Kullanıcının tarayıcısı çalışan bir Nginx sunucusuna ulaşmış olabilir; ancak Nginx isteği uygulamaya aktardığında bağlantı reddedilmiş, bağlantı beklenmedik şekilde kapanmış veya yanıt geçersiz bulunmuş olabilir. Bu nedenle 502 ekranı, sorunun mutlaka tarayıcıda ya da doğrudan Nginx hizmetinin kendisinde olduğu anlamına gelmez.

Tipik bir örnekte Nginx, bir PHP sitesinin dinamik isteğini PHP-FPM hizmetine iletir. PHP-FPM çalışmıyorsa veya yapılandırılan Unix soketi (socket) ile gerçek soket yolu uyuşmuyorsa ön katman kullanıcıya hata gösterebilir. Başka bir örnekte Nginx, 127.0.0.1:3000 adresinde çalışan bir uygulamaya vekillik yapar; uygulama yeniden başlatılırken portta dinleyici kalmadığında sorun yalnızca kısa bir süre görünür. İki senaryoda da belirtiler benzese de uygulanacak düzeltme farklıdır.

Önemli ayrım: Hata sayfasının üzerindeki logo, hangi katmanın hata yanıtını ürettiğine dair ipucu verebilir; fakat kesin tanı için ilgili zaman aralığındaki erişim ve hata günlüklerini incelemek gerekir. Önce isteğin hangi noktada kesildiğini belirlemek, rastgele ayar değiştirmenin yaratacağı ek kesintileri önler.

502, 500, 503 ve 504 Arasındaki Farklar

Birbirine yakın görünen sunucu hata kodlarını ayırmak, tanılama süresini kısaltır. Aşağıdaki tablo, kodların genel anlamını ve ilk bakışta hangi katmanın incelenebileceğini özetler. Gerçek uygulamalarda ara katmanlar farklı durumları yeniden eşleyebileceğinden, kod tek başına nihai teşhis değildir.

Örneğin arka uç uygulaması düzgün biçimlendirilmiş bir 500 yanıtı gönderirse, ön katman bu yanıtı kullanıcıya iletebilir. Buna karşılık uygulamanın bağlantıyı yanıt başlıkları gönderilmeden kapatması farklı bir hata davranışına yol açabilir. Bu yüzden yalnızca tarayıcıdaki sayfaya bakarak zaman aşımı, bağlantı reddi ve uygulama çökmesini aynı sorun gibi değerlendirmeyin.

İstek Zincirinde Hata Nerede Oluşur?

Bir web isteği tarayıcıdan başlayıp içerik dağıtım ağına, yük dengeleyiciye, Nginx'e, uygulama sunucusuna ve veri tabanına kadar uzanabilir. Her kurulumda bu katmanların tamamı bulunmaz. 502 tanılamasının temel sorusu, isteği alan son sağlıklı katmanın hangisi olduğudur. Örneğin statik dosyalar açılıyor ancak dinamik sayfalar hata veriyorsa web sunucusunun tamamen kapalı olması daha düşük olasılıktır; PHP-FPM veya uygulama bağlantısı daha güçlü bir adaydır.

Katmanları birbirinden ayırma

• Tarayıcıdan görülen durum: Hatanın tüm kullanıcılarda mı, belirli bir ağda mı, yoksa tek bir sayfada mı ortaya çıktığını belirleyin.
• Ön katman: Nginx erişim günlüğünde isteğin karşılanıp karşılanmadığını ve hangi durum kodunun kaydedildiğini kontrol edin.
• Arka uç: Uygulamanın ilgili portta veya sokette dinleyip dinlemediğini, işlem günlüklerinde çökme olup olmadığını araştırın.
• Bağımlılıklar: Veri tabanı gibi bağımlılıklardaki sorunların uygulamayı kilitleyip kilitlemediğini değerlendirin; bağımlılık hatası tek başına otomatik olarak 502 anlamına gelmez.

Çok katmanlı mimaride birden fazla ters vekil varsa, hata sayfasını hangi katmanın ürettiği ayrıca önem kazanır. Dış katmanın günlüğünde üst sunucu olarak iç vekil görünürken iç vekilin günlüğünde uygulama adresi görünebilir. Aynı isteğin zamanı ve yolu üzerinden günlükleri eşleştirmek, yanlış makinede müdahale etme riskini azaltır.

502 Hatasının Yaygın Nedenleri

Bir 502 hatası tek bir ayara indirgenemez. Değişiklik yapmadan önce aşağıdaki olasılıkları gözlenen belirtiyle eşleştirin:

• Çalışmayan arka uç: Uygulama veya PHP-FPM hizmeti durmuş, başlatma hatası almış ya da yanlış portta dinliyor olabilir.
• Yanlış yönlendirme: Nginx yapılandırmasındaki proxy_pass veya fastcgi_pass değeri gerçek hedefle uyuşmayabilir.
• Soket erişimi: Unix soketinin yolu doğru olsa bile Nginx işleminin erişim izni yetersiz olabilir.
• Kaynak baskısı: Bellek tükenmesi, işlem çökmesi veya işçi süreçlerin dolması arka ucun bağlantıları kabul etmesini engelleyebilir.
• Erken kapanan yanıt: Uygulama, geçerli yanıt başlıkları tamamlanmadan bağlantıyı kapatabilir.
• Dağıtım geçişi: Yeni sürüm başlatılmadan eski uygulama durdurulmuşsa kısa süreli bağlantı boşluğu oluşabilir.
• Ağ kuralı: Arka uç başka sunucudaysa güvenlik duvarı, rota veya hedef adresindeki değişiklik bağlantıyı kesebilir.

Belirtiyi nedene bağlayın: Bir dağıtımdan hemen sonra başlayan hata için önce hedef portu ve yapılandırmayı; yalnızca yoğun saatlerde görünen hata için kapasiteyi; yalnızca PHP sayfalarında görünen hata için PHP-FPM bağlantısını incelemek genellikle daha verimlidir. Nginx, üst sunucu seçimi ve yanıt işleme sırasında oluşan bazı sorunları 502 olarak kullanıcıya yansıtabilir.

İlk Kontroller ve Tanılama Sırası

Üretim ortamında ilk hedef, kapsamı anlamak ve kanıt toplamaktır. Rastgele yeniden başlatma, geçici iyileşme sağlasa bile asıl nedeni gizleyebilir. Komutları çalıştırmadan önce sunucudaki dağıtım modelini, yetkilerinizi ve olası kullanıcı etkisini doğrulayın.

1. Hatanın kapsamını kaydedin: İlk görülme saatini, etkilenen alan adlarını, URL yollarını ve sürekli mi aralıklı mı olduğunu not alın.
2. Son değişiklikleri denetleyin: Kod dağıtımı, sertifika değişimi, sunucu yeniden başlatması veya güvenlik duvarı düzenlemesi olup olmadığını kontrol edin.
3. Ön katman günlüklerini okuyun: İlgili zaman aralığında bağlantı reddi, izin sorunu veya erken kapanma ifadeleri arayın.
4. Arka uç hizmetini doğrulayın: Hizmetin etkin durumda olmasının yanı sıra doğru port veya sokette gerçekten dinlediğini teyit edin.
5. Yerel bağlantıyı deneyin: HTTP arka ucu varsa ön katmanın bulunduğu makineden uygulamaya istek gönderin.
6. Kaynak durumunu inceleyin: Bellek, disk ve hizmet günlüklerinde süreç kapanmasına ilişkin belirtileri karşılaştırın.

Örnek Linux kurulumunda aşağıdaki komutlar başlangıç için kullanılabilir. Günlük dosyası yolları ve hizmet adları dağıtıma, kontrol paneline veya özel kurulumunuza göre değişebilir:

sudo systemctl status nginx
sudo tail -n 100 /var/log/nginx/error.log
sudo journalctl -u nginx --since '30 minutes ago'
free -h
df -h

Arka uç HTTP üzerinden yerel bir portta çalışıyorsa, yalnızca kendi sunucunuzdaki hedefe yönelik bir kontrol gerçekleştirin:

curl -i --max-time 5 http://127.0.0.1:3000/

Bu testin başarılı olması, bütün uygulama yollarının sorunsuz olduğunu kanıtlamaz; fakat ön katmandan bağımsız olarak temel bağlantının kurulabildiğini gösterir. Test başarısızsa önce uygulamanın gerçekten 3000 portunu kullanıp kullanmadığını doğrulayın. Bir örnek portu üretim yapılandırmasına varsayılan değer gibi kopyalamayın.

Nginx ve Arka Uç Bağlantısını İnceleme

Nginx günlüklerinde geçen upstream ifadesi, isteğin iletilmeye çalışıldığı hedefi belirlemede değerlidir. connection refused çoğunlukla hedefte bağlantıyı kabul eden bir hizmet bulunmadığını; izin reddi ifadesi ise özellikle soket tabanlı kurulumda erişim sorununu düşündürür. Günlükteki tam hedef adresini yapılandırmadaki değerle karşılaştırın. Hedefin doğru görünmesi, arka uç işleminin sağlıklı olduğu anlamına gelmez.

HTTP uygulamasına yönlendirme yapılan örnek bir Nginx yapılandırması aşağıdaki gibi olabilir. Bu örnek, mevcut sanal sunucu ayarlarının tamamı değildir; doğrudan kopyalamadan önce kurulumunuza uyarlayın:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

proxy_pass hedefi ile uygulamanın dinlediği adres ve port farklıysa sorunu yalnızca zaman aşımını artırarak çözemezsiniz. Önce gerçek hedefi doğrulayın. Yapılandırmayı değiştirdiğinizde etkinleştirmeden önce sözdizimini sınayın; test başarılıysa kontrollü biçimde yeniden yükleyin:

sudo nginx -t
sudo systemctl reload nginx

Yeniden yükleme sonrasında aynı isteği yeniden deneyin ve hata günlüğünün yeni kayıtlarını kontrol edin. Sorun yalnızca yavaş işlemlerde görülüyorsa zaman aşımı değerleri incelenebilir; ancak yavaş veri tabanı sorgusunu sadece bekleme süresini uzatarak kalıcı biçimde düzeltmek mümkün değildir. Nginx'in yapılandırma sınaması ve yeniden yükleme davranışı, değişiklikleri uygularken ayrı ayrı değerlendirilmelidir.

PHP-FPM Kaynaklı Sorunları İnceleme

PHP tabanlı bir sitede Nginx statik içerikleri sunuyor, fakat PHP sayfalarında hata oluşuyorsa PHP-FPM ile FastCGI bağlantısını inceleyin. Nginx yapılandırmasındaki fastcgi_pass değeri bir TCP adresi veya Unix soketi olabilir. Bu değerin PHP-FPM havuzundaki listen ayarıyla eşleşmesi gerekir. PHP-FPM havuzunun dinleme ayarı ve eşzamanlı isteklere sınır koyan pm.max_children değeri, tanılama sırasında incelenmesi gereken iki ayrı noktadır.

Önce yüklü PHP sürümünü ve ilgili hizmet adını belirleyin; aşağıdaki örnekteki sürümü kendi sunucunuzdaki sürümle değiştirin:

sudo systemctl status php8.3-fpm
sudo journalctl -u php8.3-fpm --since '30 minutes ago'
sudo ss -ltnp

Unix soketi kullanıyorsanız dosyanın varlığını ve erişim bilgilerini, gerçek soket yolunu öğrendikten sonra inceleyin:

sudo ls -l /run/php/

Havuz kapasitesi de önemlidir: pm.max_children eşzamanlı işlenebilecek istek sayısını sınırlar. Değeri düşünmeden artırmak, her işçi sürecinin kullandığı bellek nedeniyle sunucuyu daha da zorlayabilir. Önce iş yükünü, bellek tüketimini, kuyruklanmayı ve uygulamanın yavaş işlemlerini ölçün. PHP-FPM hizmeti sık sık kapanıyorsa hizmet günlüğünü ve sistemin bellek baskısını birlikte değerlendirin; yalnızca Nginx tarafındaki hata ekranına bakmak yeterli değildir.

Tekrarlayan 502 Hatalarını Önleme

Olay çözüldükten sonra hangi bileşenin, hangi saatte ve hangi nedenle yanıt veremediğini kaydedin. Kalıcı çözüm, yalnızca hizmeti yeniden başlatmak değil, aynı koşul tekrar oluştuğunda erken uyarı alabilmektir.

• Sağlık kontrolleri: Uygulamanın yalnızca port açtığını değil, temel bir isteğe beklenen yanıtı verdiğini izleyin.
• Kaynak izleme: Bellek, işlemci, disk alanı ve uygulama işçi süreçlerini düzenli takip edin.
• Günlük saklama: Ön katman ve uygulama günlüklerini olay saatlerini karşılaştırabilecek şekilde yönetin.
• Dağıtım planı: Yeni sürümü hazır hale getirmeden çalışan örneği devreden çıkarmamaya çalışın; geri dönüş adımlarını önceden belirleyin.
• Yapılandırma kontrolü: Port, soket ve hedef sunucu değişikliklerini dağıtım öncesinde doğrulayın.
• Kapasite planlaması: Tekrarlanan yoğunluk sorunlarında uygulama optimizasyonu ile kaynak artırımı seçeneklerini birlikte değerlendirin.

Örneğin bir e-ticaret sitesi yalnızca kampanya başlangıcında 502 veriyorsa olay sonrası raporda istek hacmi, uygulama işlem süresi, PHP-FPM işçi kullanımı ve bellek tüketimi birlikte incelenmelidir. Buna karşılık her dağıtımdan sonra yaklaşık bir dakikalık hata oluşuyorsa öncelik, kaynak artırımı değil sürüm geçiş sırasıdır. İki belirtiye aynı çözümü uygulamak maliyet yaratabilir ve kesintiyi sürdürür.

Yedekleme de toparlanma planının parçasıdır; ancak yedek, çalışmayan bir arka uç bağlantısının doğrudan çözümü değildir. Yapılandırma veya uygulama değişikliğini geri almanız gerektiğinde, daha önce sınanmış bir geri yükleme süreci değer kazanır. Bu nedenle izleme, değişiklik yönetimi ve geri yükleme hazırlığını birlikte ele alın.

Sıkça Sorulan Sorular

Sonuç

502 Bad Gateway hatasını çözmenin en güvenilir yolu, kullanıcı isteğinin hangi katmana kadar ulaştığını belirlemek, ilgili zaman aralığındaki günlükleri okumak ve arka ucun gerçek bağlantı adresini doğrulamaktır. Nginx yapılandırması, PHP-FPM havuzu, uygulama sağlığı ve sistem kaynakları birlikte incelendiğinde geçici belirti ile kök neden birbirinden ayrılabilir. Tekrarlanan olaylarda ise sağlık kontrolleri, kapasite takibi ve kontrollü dağıtım süreci kesinti riskini azaltmaya yardımcı olur.

İş yükünüz için uygun altyapıyı değerlendiriyorsanız Corelux Hosting, Sanal Sunucu ve Kiralık Sunucu seçeneklerini inceleyebilirsiniz. Geri dönüş planınızı güçlendirmek için Yedekleme Hizmeti de değerlendirilebilir; uygun seçim, uygulamanızın kaynak ve yönetim ihtiyaçlarına bağlıdır.