502 Bad Gateway

一言でいうと（このエラーが何を意味するか）

502 Bad Gateway は、ゲートウェイまたはプロキシとして動作するサーバーが、上流（upstream）サーバーへリクエストを転送したものの、有効な HTTP 応答を受け取れなかったことを示すステータスコードです。RFC 9110 では「上流サーバーから無効な応答を受け取った」と定義されます。

ここで決定的に重要なのは、502 を返しているのはクライアントに一番近いリバースプロキシ／ロードバランサであり、実際に壊れているのはその背後の上流アプリ、または両者をつなぐ接続だという点です。nginx や ALB、Cloudflare が「502」を出しても、それらのソフト自体は正常に動いています。エラーページを出せている時点でプロキシは生きており、問題は上流にあります。

横にスクロール

よくある原因（複数を具体的に、頻度順）

1. 上流アプリのプロセスがクラッシュ／未起動: 最も多い原因。デプロイ失敗、OOM Killer による強制終了、設定ミスによる起動失敗などでアプリが listen していない、または途中で落ちる。プロキシは接続先へつなげず（Connection refused）502 を返す。
2. 上流の過負荷によるワーカー枯渇: リクエスト数がワーカー／プロセス数を超え、新規接続がバックログ上限（listen backlog）を超えて拒否される。負荷スパイク時に断続的な 502 として現れる。
3. 上流の応答が途中で切れる・不正: アプリが接続を確立した後にセグメンテーション違反やタイムアウトで接続を早期クローズし、ヘッダを返し終える前に切断する。nginx はこれを upstream prematurely closed connection として 502 にする。
4. プロキシ〜上流間のタイムアウト（接続確立の失敗）: proxy_connect_timeout 内に TCP 接続を確立できない場合。ネットワーク分断、上流のヘルス悪化、ファイアウォールやセキュリティグループの誤設定で発生。なお応答本文が遅いことによるタイムアウトは通常 504。
5. 上流が返すヘッダの破損・巨大化: ヘッダサイズがプロキシのバッファ上限を超える、あるいは不正なステータス行を返す。upstream sent too big header などが典型。
6. keepalive の不整合: 上流がアイドル接続を先に閉じたのに、プロキシが同じ接続を再利用しようとして失敗する競合。トラフィックが少ない時間帯に散発する 502 の典型パターン。

診断の手順（切り分け方・見るべきログ/コマンド）

原因層を上から潰していきます。順番が重要です。

手順1: 上流プロセスの生死を確認する。

# 上流が想定ポートで listen しているか
ss -ltnp | grep -E ':(8000|9000|3000)'
# プロセスが動いているか（例: gunicorn / php-fpm）
systemctl status gunicorn
# 直近でOOM Killerに殺されていないか
dmesg -T | grep -i 'killed process'

手順2: プロキシのエラーログで上流エラーの種別を読む。 nginx なら error.log に理由が明記されます。ここで原因の 8 割が判明します。

tail -n 100 /var/log/nginx/error.log | grep -i upstream
# 代表的な出力と意味:
# connect() failed (111: Connection refused)      -> 上流が起動していない/落ちている
# upstream prematurely closed connection          -> 上流が応答途中で切断（クラッシュ等）
# upstream timed out (110) while connecting        -> 接続確立に失敗（→504ではなく502側）
# upstream sent too big header                     -> ヘッダがバッファ超過

手順3: 上流へ直接アクセスして層を切り分ける。 プロキシを介さず上流を叩き、正常応答が返るかを見ます。

# ローカルの上流に直接リクエスト（プロキシをバイパス）
curl -sv http://127.0.0.1:8000/healthz

ここで正常なら問題はプロキシ〜上流間（ネットワーク・タイムアウト・keepalive）に、異常なら上流アプリ自体にあります。ロードバランサ配下なら、ターゲットグループ／バックエンドのヘルスチェック状態も必ず確認します（AWS ALB なら Target health、GCP なら backend health）。

手順4: 503／504 と区別して原因層を確定する。 これが最短の切り分けです。

要点は、502 は「返ってきた応答が壊れている」、504 は「そもそも返ってこない（遅すぎる）」、503 は「受け付ける先がない／わざと断っている」という違いです。504 が出るなら上流は生きていて遅いだけなので、調査対象はクエリ性能や外部 API 待ちに移ります。503 で上流台数がゼロなら、まずデプロイ／ヘルスチェック設定を疑います。

解決と予防（対処と再発防止）

即時の対処は原因層に対応します。

• 上流がクラッシュ／未起動: プロセスを再起動し、起動ログでエラーを確認する。OOM が原因ならメモリ上限やワーカー数を見直す。
• ワーカー枯渇: 一時的にワーカー／プロセス数を増やし、listen backlog を拡張する。根本的には水平スケールやオートスケールの閾値を調整する。
• タイムアウト系: 上流の処理時間の実態に合わせて proxy_connect_timeout などを調整する。ただし値を延ばすのは対症療法で、遅い原因の除去が本筋。

再発防止では設定の整合を取ります。とくに keepalive 起因の散発 502 は、上流のアイドルタイムアウトをプロキシ側より長くするのが定石です。

upstream app {
    server 127.0.0.1:8000;
    keepalive 32;                 # プロキシ側で接続をプール
}
server {
    location / {
        proxy_pass http://app;
        proxy_http_version 1.1;    # keepalive には 1.1 が必須
        proxy_set_header Connection "";
        proxy_next_upstream error timeout http_502;  # 502時は別の上流へ再試行
    }
}

HTTP のステータスコード体系やプロキシの位置づけはWebを、TCP 接続確立・タイムアウトの原理はネットワークを、上流のオートスケールやローリングデプロイの設計はDevOpsを参照してください。