502 Bad Gateway Açıklaması: Ne Anlama Gelir, Neden Olur ve Nasıl Giderilir

Anahtar Kelimeler

Bu hızlı sözlük, daha derin açıklama aşamasında en çok kafa karışıklığı yaratabilecek altyapı terimlerini kapsamaktadır.

502 Hatası Neden Bu Kadar Rahatsız Edici Hissettirir

Bir dağıtım yaparsınız, siteyi yeniden yüklersiniz ve alan adı anında yanıt verir — yalnızca uygulamanızla değil. Ya da bir müşteri Ödeme’ye tıklar, sayfa yüklenir ve işlem sade bir 502 Bad Gateway mesajının arkasında çöker. Bu hatayı bu kadar stresli yapan da budur: site erişilebilir durumdadır, ancak aktarımı tamamlayacak kadar sağlıklı değildir.

502, garip bir ara durumda yer alır. Tam bir kaybolma gibi görünmez, ama çalışan bir hizmet gibi de davranmaz. Geliştiriciler için bozuk bir dağıtım veya API zinciri anlamına gelebilir. İş sahipleri için kayıp güven veya kesintiye uğrayan gelir. Ekipler için ise en kötü kısım genellikle sahipliktir: hangi katman aslında sorunu üstleniyor?

Buna yaklaşmanın yararlı yolu tahmin etmek değildir. Önce hatanın ne anlama geldiğini tanımlayın. Ardından istek zincirindeki yerini belirleyin. Sonra hatayı mantıksal olarak, bir aktarım noktasını ele alarak giderin. Zinciri görebildiğinizde, hata rastgele görünmeyi bırakır.

502 Bad Gateway Aslında Ne Anlama Gelir

Bir 502 Bad Gateway hatası genellikle, gateway veya proxy olarak görev yapan bir sunucunun arkasındaki bir sonraki katmandan aldığı yanıtı kullanamadığı anlamına gelir. Sade bir ifadeyle: bir sunucu isteğinizi başka bir sunucuya iletmeye çalıştı ve bu aktarım, ön yüzlü sunucunun normal bir sonuç döndüremeyeceği kadar kötü bir şekilde başarısız oldu.

📝 Not: Upstream geçerli bir HTTP hatası döndürürse, proxy bunu genellikle iletir. Uygulama gerçek bir 503 Service Unavailable döndürürse, ön katman normalde o 503‘ü iletmeli, 502 üretmemelidir. 502, yanıtın kendisinin kullanılamaz olduğu anlamına gelir. Zamanında kullanılabilir bir yanıt gelmezse, bu genellikle 504 olur.

5xx hatalarını yanlış okumayı bırakmanın en hızlı yolu, onları hatanın nerede yaşandığına ve ilk olarak hangi soruyu tetiklediğine göre ayırt etmektir:

⚠️ Uyarı: 500, 502, 503 ve 504‘ü tek bir genel “sunucu çöktü” kategorisinde toplamayın. Bunlar farklı hata biçimlerine işaret eder ve bu durum, önce neyi kontrol etmeniz gerektiğini değiştirir.

Bu tanım netleştikten sonra, bir sonraki soru çok daha kullanışlı hale gelir: gerçek bir yığında bu başarısız aktarım aslında nerede gerçekleşir?

Hata Gerçek Bir İstek Zincirinde Nerede Gerçekleşir

Modern isteklerin çoğu tarayıcıdan uygulamaya doğrudan gitmez. Katmanları geçer: tarayıcıdan CDN veya edge’e, edge’den reverse proxy veya load balancer’a, proxy’den uygulama sürecine. 502, bu aktarım noktalarından birinde görünür hale gelir.

Basitleştirilmiş istek zinciri: Tarayıcı → CDN/Edge → Reverse Proxy / Load Balancer → Uygulama / Süreç

Bir reverse proxy, genel isteği kabul eder ve dahili olarak iletir. Bir load balancer benzer bir şey yapar, ancak birden fazla sağlıklı hedef arasında seçim yapabilir. Her iki durumda da ön katman, iş mantığını kendisi yürütmek yerine isteği yönlendirmektedir.

Ön büro analojisi burada iyi işe yarar. Proxy’yi bir ofis binasındaki resepsiyon olarak düşünün. Ziyaretçiyi karşılar, doğru ofisi arar ve ziyaretçiyi oraya yönlendirmeye çalışır. Ofis yanıt vermezse, yanlış hatta yanıt verirse veya resepsiyonun kullanamayacağı bir yanıt verirse, resepsiyon hatayı geri döndürür. Bu nedenle görünür hata genellikle proxy katmanında ortaya çıkar; asıl neden başka bir yerde olsa bile.

📝 Not: Proxy genellikle hatanın habercisidir, asıl nedeni değil.

Bu resepsiyonun arkasındaki “bir sonraki sunucu”, bir port üzerindeki normal bir HTTP hizmeti, 127.0.0.1:3000 gibi bir uygulama dinleyicisi veya PHP-FPM gibi yerel socket destekli bir süreç olabilir. Temel sorunun proxy’de bulunması gerekmez. Kötü bir dağıtım, çökmüş bir uygulama çalışanı veya hatta bir veritabanı hatası, backend’i proxy’nin yalnızca 502’yi yüzeye çıkardığı kadar kötü bir şekilde bozabilir.

Edge hizmetleri bir ek karmaşıklık daha ekler. Cloudflare gibi bir CDN, yığınınızın daha derinindeki origin tarafı 502’yi iletebilir ya da edge-to-origin aktarımı başarısız olduğunda kendi başına bir 502 üretebilir. Bu nedenle “bu hatayı kim döndürdü?” pratik olarak ilk sorulması gereken sorudur, sonradan düşünülecek bir şey değil.

502 Hatalarının Neden Oluştuğu: Ana Hata Kategorileri

502’yi tek bir gizemli olay olarak değerlendirmeyi bıraktığınızda, neden ortamı çok daha kolay yönetilebilir hale gelir. Çoğu olay üç yeniden kullanılabilir kategoriye girer: upstream kullanılamaz durumda, aktarımın kendisi yanlış yapılandırılmış veya yanıt gateway’in kullanamayacağı bir biçimde geri dönüyor.

Birinci kategori açık olanıdır: upstream kullanılabilir durumda değildir. Belki uygulama dağıtımdan sonra çöktü. Belki hizmet hiç yeniden başlatılmadı. Belki bir PHP-FPM havuzu öldü ya da bir hedef sağlıksız olarak işaretlenip rotasyondan çıkarıldı. Bu klasik “hizmet çöktü” senaryosudur, ancak 502 ortamının yalnızca bir dilimidir.

İkinci kategori aktarım uyumsuzluğudur. Burada her iki katman da çalışıyor olabilir, ancak birbirlerine nasıl ulaşacakları konusunda anlaşmazlık yaşarlar. Proxy yanlış porta işaret ediyor olabilir. Bir ana bilgisayar adı yanlış çözümlenebilir. Bir güvenlik duvarı yolu engelleyebilir. Bir katman HTTPS beklerken diğeri yalnızca düz HTTP konuşuyor olabilir. Bir socket yolu değişmiş olabilir. Bu durumlarda uygulama sağlıklı olabilir ve katmanlar arasındaki bağlantı yine de bozuk olabilir.

Üçüncü kategori daha karmaşıktır: upstream yanıt verir, ancak gateway’in kullanabileceği bir biçimde değil. Bir hedef TCP bağlantısını sıfırlayabilir, çok erken kapatabilir, hatalı biçimlendirilmiş veya aşırı büyük başlıklar gönderebilir ya da yük altında kısmi çıktı döndürebilir. Uygulama basitçe “kapalı” değildir; gateway’in aldığını reddedecek kadar kötü yanıt veriyor.

Bu aynı zamanda 502’nin yalnızca bir zaman aşımı hikayesi olmadığının nedenidir. Bazı zaman aşımı durumları 502 değil 504 Gateway Timeout olur. Cloudflare, origin bağlantısı veya sıkıştırma bozulduğunda edge tarafından üretilen 502’leri yüzeye çıkarabilir. Load balancer’lar, kayıt silme zamanlama sorunları veya TLS el sıkışma hataları sırasında 502 yayabilir. “Hizmet çöktü” bir neden kategorisidir, hatanın tanımı değil.

Bu zihinsel model, bir yapılandırma dosyasına dokunmadan önce size gerçek bir kontrol listesi sunar. Hangi kategoride olduğunuzu sorun, ardından kanıt arayın. Sorun giderme sırasını ritüelistik yerine mantıklı hissettiren de budur.

502 Hataları için Akıllı Bir Sorun Giderme Sırası

502’yi gidermenin en hızlı yolu, hangi katmanın döndürdüğünü belirlemek, ardından o katmanın arkasındaki bir sonraki atlamayı herhangi bir şeyi değiştirmeden test etmektir. Amaç, başarısız aktarımın nerede yaşandığını kanıtlamaktır.

💡 İpucu: Herhangi bir şeyi yeniden başlatmadan veya düzenlemeden önce, 502‘yi kimin döndürdüğünü belirleyin. Temiz bir atıf adımı, insanların baskı altında denediği ilk beş “düzeltme”den genellikle daha fazla zaman kazandırır.

Aşama 1: Katmanı belirleyin

Genel taraftan başlayın ve internet’e bakan katmanın gerçekte ne döndürdüğünü sorun:

curl -I https://example.com

Bu, genel URL’den HTTP durumunu ve başlıklarını gösterir. Başlıklar açıkça bir CDN, load balancer veya reverse proxy’ye aitse, ilk ipucunuzu elde ettiniz demektir. Hata sayfası Cloudflare markalıysa, Cloudflare 502’yi kendisi üretmiş olabilir; markasızsa, edge yalnızca origin tarafı bir hatayı iletiyor olabilir. cf-error-type veya cf-error-origin gibi başlıklar Cloudflare tarafından üretilen hata sayfalarında görünebilir; bu, tam olarak her 502’de görünmedikleri için kullanışlıdır.

📝 Not: Yalnızca bir ziyaretçi hatayı görürken diğerleri siteye erişebiliyorsa, yerel VPN, proxy, güvenlik duvarı veya DNS ayarları yine de sorunun bir parçası olabilir. 502 genellikle sunucu taraflıdır, ancak izole edilmiş bir istemci yolu gözlemlediğiniz şeyi bulanıklaştırabilir.

Aşama 2: Upstream yolunu doğrulayın

Hangi katmanın 502’yi döndürdüğünü öğrendikten sonra, arkasındaki bir sonraki atlamayı test edin. Bir reverse proxy söz konusuysa, hem proxy’nin hem de backend hizmetinin çalıştığını doğrulayın ve beklenen dinleyicinin var olduğunu onaylayın:

systemctl status nginx
systemctl status <app-service>
ss -tlnp

<app-service> yerine backend hizmet adınızı yazın. systemctl status, proxy veya uygulama sürecinin çalışıp çalışmadığını, başarısız olup olmadığını veya yeniden başlatılıp başlatılmadığını söyler. ss -tlnp, beklediğiniz portta gerçekten bir şeyin dinleyip dinlemediğini gösterir.

Ardından backend’in proxy olmadan doğrudan yanıt verip vermediğini test edin:

curl -i http://127.0.0.1:3000

Doğrudan istek çalışıyor ancak genel URL hâlâ 502 döndürüyorsa, backend sağlıklı olabilir ve asıl sorun aktarım olabilir. Bu sizi yalnızca uygulama kodundan ziyade proxy hedef ayarlarına, protokol uyumsuzluklarına, upstream ana bilgisayar adlarına, TLS beklentilerine veya güvenlik duvarı kurallarına yönlendirir.

Aşama 3: Komutları tören olarak değil kanıt olarak kullanın

Doğrudan kontrollerden sonra, aktarımın neden başarısız olduğunu açıklayan kanıtlara geçin:

journalctl -u nginx -u <app-service> --since "15 min ago"
dig +short example.com
nginx -t

Bu üç kontrol farklı soruları yanıtlar. journalctl, son çökmeleri, sıfırlamaları, zaman aşımı ipuçlarını ve dağıtımla ilgili hataları ortaya çıkarır. dig +short, güvendiğiniz ana bilgisayar adının sunucunun beklediği şekilde çözümlenip çözümlenmediğini söyler. nginx -t, herhangi bir şeyi yeniden yüklemeden önce reverse proxy sözdizimini doğrular; bu önemlidir çünkü hatalı bir upstream tanımı, backend sağlıklı olsa bile 502 üretebilir.

Pratik sinyaller genellikle şöyle görünür:

Hatırlanması gereken temel kalıp budur: katmanı belirleyin, bir sonraki atlamayı doğrulayın, ardından uyumsuzluğu açıklamak için günlükleri ve doğrudan testleri kullanın. Önce kanıt. Sonra ayarlar.

Sorun Giderme Yolu Hosting Modeline Göre Nasıl Değişir

502 sonrasındaki bir sonraki adım, yığının ne kadarını kontrol ettiğinize bağlıdır. Sorun giderme mantığı aynı kalır, ancak kendiniz inceleyebileceğiniz miktar paylaşımlı hosting, VPS, dedicated sunucular ve edge proxy kurulumları arasında büyük ölçüde değişir.

📝 Not: Paylaşımlı hostingde yükseltme yapmak bir kaçış değildir. Genellikle doğru teknik adımdır; çünkü 502 için en önemli katmanlar görünürlüğünüzün dışında olabilir.

Paylaşımlı hostingde yapabileceğiniz en yararlı şey kanıt toplamaktır: zaman, etkilenen URL, hatanın sabit mi yoksa aralıklı mı olduğu ve bir dağıtım veya yapılandırma değişikliğinden sonra mı başladığı. Bu, desteğe eyleme geçirilebilir bir şey verir. Reverse proxy’yi, uygulama hizmetini veya sunucu günlüklerini kontrol etmiyorsanız, anlamlı katman katman tanı hızla sona erer.

Bir VPS’de, hizmetleri, dinleyicileri, günlükleri ve proxy yapılandırmasını doğrudan inceleyebildiğiniz için tam iş akışı gerçekçi hale gelir. Reverse proxy sorun giderme işlemi buraya aittir. AlexHost VPS altyapısında systemctl, journalctl, ss, upstream hedefleri ve Nginx yapılandırmasını kontrol etmek, her zaman destek arkasına gizlenmiş bir şey değil, normal sahipliğin bir parçasıdır.

Dedicated sunucu size aynı görünürlüğü verir, ancak daha fazla sorumlulukla. Tam yığının daha fazlasına ve muhtemelen çevreleyen ağ varsayımlarının da daha fazlasına sahipsinizdir. Önüne bir CDN veya başka bir edge hizmeti eklerseniz, ilk sahiplik sorusu aynı kalır: edge 502’yi kendisi mi üretti, yoksa origin tarafı bir hatayı mı iletti? Daha fazla kontrol, sorun gidermeyi varsayılan olarak daha basit yapmaz. Size inceleyebileceğiniz daha fazla yer verir.

Panikle Değil, Katmanlarla Düşünün

Bir 502 Bad Gateway hatası, onu genellikle olduğu şey olarak ele aldığınızda gizemini yitirir: rastgele bir tarayıcı olayı değil, başarısız bir sunucudan sunucuya aktarım. Tarayıcı yalnızca fark ettiğiniz yerdir. Gerçek hikaye, isteği bir sonrakine ileten ve geri kullanılabilir bir şey alamayan katmanda yaşar.

Bu nedenle sırayı basit tutun: katmanı belirleyin, bir sonraki atlamayı kontrol edin, doğrudan testler ve günlüklerle doğrulayın ve yalnızca kanıt belirli bir yere işaret ettiğinde ayarları değiştirin. Tekrarlayan olaylar sizi daha derin günlük, proxy ve hizmet görünürlüğüne doğru itmeye devam ediyorsa, bu noktada daha yüksek kontrollü ortamlar — AlexHost VPS veya dedicated sunucular dahil — pazarlama nedenleriyle değil, operasyonel nedenlerle kullanışlı hale gelir. Burada yöntem, ezberlemenin önüne geçer.