はじめに
本記事では、AWS ALB（Application Load Balancer）と Fargate 上で稼働する FastAPI アプリケーションの構成において「502 Bad Gateway」エラーが発生した際の、原因特定と対処方法について整理します。
個人の備忘録程度の走り書きとなっておりますが、温かい目で見守っていただければ幸いです。
よくある原因と対処法
① FastAPIアプリが 0.0.0.0 で起動していない
-
NG例:
uvicorn main:app（デフォルトでは127.0.0.1:8000） -
OK例:
uvicorn main:app --host 0.0.0.0 --port 8000
Fargate 環境では、
0.0.0.0でバインドしないと外部（ALB）からアクセスできません。
② ALBのターゲットグループのヘルスチェックが FastAPI に存在しない（これから調査）
- 例：ターゲットグループのヘルスチェックパス
/healthを設定していて、FastAPI 側にそのエンドポイントが存在しない場合、ターゲットが常にunhealthyとなり、結果として502エラーになる可能性が高い。
# FastAPI 側でのヘルスチェックエンドポイントの追加例
@app.get("/health")
def health_check():
return {"status": "ok"}
③ ターゲットグループと FastAPI のポート不一致
- FastAPI の起動ポートと、ALB のターゲットグループが指定しているポートが一致していない場合も
502が発生します。 - 例：FastAPI を
--port 8000で起動している場合 → ターゲットグループのポートも 8000 に設定する必要があります。
④ セキュリティグループの設定ミス
- ALB のセキュリティグループから、Fargate のセキュリティグループに対して TCP 8000 ポートのインバウンド通信が許可されていない場合、通信できずに
502となります。
⑤ FastAPI コンテナが内部エラーで応答していない
- 表面的には Uvicorn が起動していても、FastAPI のアプリ内部で例外が発生していたり、起動処理が失敗していることがあります。
-
aws logsコマンドや CloudWatch Logs を確認して、エラーの有無をチェックします。
チェックリスト（簡易版）
| チェック項目 | 確認結果 |
|---|---|
FastAPI が 0.0.0.0 で待ち受けているか |
✅ |
| ポート8000で起動しているか | ✅ |
| ターゲットグループがポート8000に向いているか | ✅ |
| ターゲットグループのヘルスチェックパスが FastAPI 側にあるか | ✅ |
| セキュリティグループで ALB→Fargate 通信が許可されているか | ✅ |
| FastAPI のログにエラーがないか | ✅ |
補足：ログに「エラーがない」ように見えても
INFO ログしか出ていない場合でも、コンテナ内のアプリが正しく処理を返せていないケースがあります。
リクエストに対して 500 を返していたり、タイムアウトしている可能性も含めて、アプリケーションログと ALB のターゲットステータス（unhealthy）などを合わせて確認してみてください...！
まとめ
本記事で紹介したように、ALB との組み合わせでよく発生する 502 Bad Gateway の多くは、「アプリが適切に公開されていない」「ヘルスチェック失敗」が原因です。
現時点では問題はまだ解消していませんが、これらの観点をもとに、引き続き原因を切り分けながら確認を進めていく予定です。
1つずつ設定を丁寧に見直すことで、安定したデプロイ環境を構築できるはずです。ALB との組み合わせでよく発生する 502 Bad Gateway の多くは、「アプリが適切に公開されていない」「ヘルスチェック失敗」が原因です...！