502 Bad Gateway

このエラーの意味と見分け方

• ブラウザに 502 Bad Gateway または Bad Gateway と表示されます。Nginx、Apache、Cloudflareなど、プロキシのブランドが表示される場合もあります。
• 複数のユーザーに影響したり、デプロイや設定変更の直後に発生したり、トラフィック増加時に現れたりします。
• バックエンドのワーカー、メモリ、CPU、データベース接続が枯渇すると、断続的に発生することがあります。
• プロキシログに、上流への接続失敗、タイムアウト、読み取れないステータスライン、不正な応答、サイズ超過したヘッダー、またはソケットエラーが記録されます。
• オリジンへの直接リクエストは成功する一方、CDN経由の同じリクエストが502になる場合は、CDNからオリジンへのアクセス、ファイアウォール、TLS、またはルーティングの問題が考えられます。

可能性の高い順の主な原因

1. 停止またはクラッシュしているバックエンド: PHP-FPM、Node.js、Gunicornなどのアプリケーションプロセスが停止している、クラッシュループに陥っている、またはデプロイ後の起動に失敗している。
2. バックエンドの過負荷またはタイムアウト: ワーカー、メモリ、CPU、データベース接続、その他の依存サービスが枯渇し、プロキシが時間内に応答を取得できない。
3. 上流設定の誤り: プロキシが誤ったホスト、ポート、コンテナアドレス、Unixソケット、またはアプリケーションパスを参照している。
4. ソケットまたは内部ファイアウォールによるアクセス失敗: ソケット権限、ネットワークポリシー、ファイアウォール、またはセキュリティグループの変更により、プロキシがバックエンドに到達できない。
5. 無効またはサイズ超過したバックエンド応答: アプリケーションが不正な出力、利用できないステータスライン、またはプロキシが受け入れられないサイズのヘッダーを送信している。
6. CDNからオリジンへの接続失敗: CDNがオリジンに到達できない、オリジンのファイアウォールによってブロックされている、またはオリジン設定で想定されているHTTPS接続を確立できない。

修正方法

1. 502がどこで生成されているかを特定する

エラーページがNginx、Apache、Cloudflare、ホスティングプラットフォーム、その他の中間サーバーのどれによって表示されているかを確認します。すべてのルートで失敗しているのか、特定のアプリケーションパスだけで失敗しているのかを確認し、発生時刻と影響を受けたURLを記録します。これにより、該当するログとリクエストを照合できます。

2. バックエンドプロセスとそのログを確認する

認証済みのサーバーまたはホスティングパネルへのアクセス権限を使用し、アプリケーションプロセスが稼働していて処理を受け付けているか確認します。クラッシュループ、致命的なアプリケーションエラー、メモリ不足による終了、依存関係の不足、起動失敗がないかログを確認します。

たとえば、読み取り専用のサービス確認には次のようなコマンドを使用できます。

systemctl status php8.2-fpm
systemctl status nginx
pm2 status

インストールされているPHP-FPMのバージョンとプロセスマネージャーに合わせて使用し、これらの名前をそのままコピーしないでください。バックエンドが停止またはクラッシュループしている場合は、まず根本原因を修正します。その後、通常の変更手順に従って対象サービスの再起動を検討してください。再起動はリクエストを中断し、実行時の有用な情報を失わせる可能性があるため、事前に許可を確認し、関連ログを取得しておきます。

3. プロキシのエラーログを確認する

ログのタイムスタンプを失敗したリクエストと照合します。Nginxでは、設定されているエラーログを確認します。一般的な場所は /var/log/nginx/error.log です。mod_proxy または mod_proxy_fcgi を使用するApacheでは、Apacheのエラーログを確認します。

次のような違いに注目します。

• connect() failed: プロキシが設定された上流に接続できない。
• upstream timed out: バックエンドまたはその依存サービスの処理が遅すぎる、または過負荷になっている。
• upstream sent too big header: 応答ヘッダーが設定されたプロキシバッファーの容量を超えている。
• ステータスラインの読み取りエラー: バックエンドが接続を閉じた、または無効な応答を返した。

正確なログの場所とメッセージ形式は、サーバーとホスティングプラットフォームによって異なります。

4. 上流のホスト、ポート、またはソケットを確認する

リバースプロキシの設定を確認します。Nginxでは、proxy_pass または upstream ブロックを確認します。Apacheでは、ProxyPass、ProxyPassMatch、およびPHP-FPMの接続設定を確認します。

必要に応じて、読み取り専用のリスナー確認とローカルリクエストを実行します。

ss -tlnp
curl http://127.0.0.1:PORT

PORT は設定されているアプリケーションポートに置き換えます。アプリケーションがUnixソケットを使用している場合は、パスが存在し、プロキシプロセスがアクセスできることを確認します。PHP-FPMでは、プールの listen 設定がApacheまたはNginxに設定されたアドレスまたはソケットと一致している必要があります。この確認のためだけに、内部テスト用エンドポイントを公開しないでください。

5. 過負荷、依存サービス、タイムアウトを調査する

バックエンドが稼働しているものの、トラフィック急増や遅いリクエストと同時に障害が発生する場合は、CPU、メモリ、ワーカー数、データベース接続数、キューの深さ、ホスティングパネルのリソース制限を確認します。プロセスが稼働中でも、追加の処理を受け付けられない場合があります。

根拠なしにプロキシのタイムアウトやバッファーサイズを増やさないでください。ログでヘッダーサイズ超過が示されている場合は、アプリケーションの応答を調査し、関連するNginxの proxy_buffer_size と proxy_buffers の設定を確認します。設定変更が必要な場合は、承認済みの変更手順に従って検証・適用してください。許可なく本番プロキシをリロードしてはいけません。

6. オリジンとCDN経由の経路を比較する

CloudflareなどのCDNをサイトの前段に配置している場合は、適切なオリジンアドレスと Host ヘッダーを使用して、許可を得たうえでオリジンに直接アクセスします。結果を公開URLへのリクエストと比較します。

• オリジンでも失敗する: オリジン側のアプリケーション、プロキシ、ソケット、ポート、ファイアウォール、リソースの状態を調査します。
• オリジンは成功するがCDNが失敗する: CDNからオリジンへのファイアウォールルール、オリジンへの到達性、ルーティング、CDNのオリジンSSL/TLSモードを確認します。オリジンが、CDNの想定するプロトコルと証明書設定を提示していることを確認します。

7. 原因を修正した後に再テストする

まずオリジンが想定どおりの応答を返すことを確認します。次に、リバースプロキシまたはCDN経由でリクエストをテストします。一部のURLだけが失敗する場合は、一般的な障害として扱うのではなく、それらのアプリケーションルート、応答サイズ、認証要件、バックエンドの依存関係を比較します。

8. ホスティングパネルの制限を確認する

cPanel、Plesk、または同様の共有ホスティングでは、PHP-FPMとリソース使用量のログを確認します。アカウントが、プロバイダーによって設定されたプロセス数、メモリ、または同時実行数の制限に達している可能性があります。制限を変更できない場合は、障害の発生時刻、影響を受けたルート、関連するログメッセージをホスティング事業者に伝え、インフラストラクチャレベルの記録を調査してもらいます。

予防と修正確認

• アプリケーションをプロセス監視下で実行し、自動再起動だけに頼らず、繰り返し発生するクラッシュを監視します。
• リクエストに影響が出る前に、メモリ、CPU、ワーカー使用量、データベース接続、キューの深さ、ホスティングパネルの制限を監視します。
• アプリケーション、プロキシ、ロードバランサー、CDN間で意図した互換性のあるタイムアウトを設定します。不健全なバックエンドを隠すために、タイムアウトを長くしないでください。
• デプロイや設定変更の後に、想定されるアプリケーションポートまたはソケットを確認します。
• オリジンTLS、ファイアウォールルール、プロキシ設定を変更した後は、代表的なルートをオリジンに直接、またCDN経由でテストします。
• プロキシとアプリケーションのログを時刻同期した状態で保持し、断続的な502応答をバックエンドのイベントと照合できるようにします。
• 環境ごとに、担当サービス、上流アドレス、ソケット権限、承認済みの復旧手順を文書化します。

よくある質問