- nginx の裏のアプリにつないだら、502 Bad Gateway や 504 Gateway Timeout が出た
- どちらも「アプリがおかしい」のは分かるが、どこから調べればいいか分からない
- Gunicorn の timeout や proxy_read_timeout を延ばせばいいのか迷っている
502 と 504 は、どちらも nginx が裏のアプリ(upstream)から正しい返事を受け取れなかったときに出ます。原因はいくつかありますが、nginx のエラーログに出る1行でほぼ見分けられます。
この記事では、手元の Docker で nginx と Gunicorn を動かし、502 と 504 をわざと起こしました。エラーログの文言ごとに、原因と直し方をまとめます。
試してみると、よく言われることと違う結果もありました。
Gunicorn の timeout を超えた処理は 502 ではなく 500 になり、アプリを止めたまま nginx を再起動すると、nginx が起動しませんでした。
nginx からアプリへ転送する設定そのものは、こちらの記事で書いています。

| 項目 | 内容 |
|---|---|
| nginx | nginx 1.30.6(Docker の nginx:1.30-alpine) |
| アプリ | Gunicorn 23.0.0(python:3.12-alpine、-w 1 --timeout 10)。指定した秒数だけ待ってから返す小さな WSGI アプリ |
| わざと切るサーバー | リクエストを読んだら、返事をせずに接続を切るだけの Python のサーバー |
| 動かした場所 | Mac の Docker Desktop(docker compose) |
結論:502 は「返事がおかしい」、504 は「待ちきれなかった」
先に、実験の結果をまとめます。
| 状況 | ステータス | エラーログ(要点) |
|---|---|---|
| 転送先のポートの誤り | 502 | connect() failed (111: Connection refused) |
| アプリが返事をせずに切る | 502 | upstream prematurely closed connection |
| proxy_read_timeout(3秒)を超える処理 | 504 | upstream timed out (110: ...) while reading response header |
| Gunicorn の timeout(10秒)を超える処理 | 500 | 出ない(アプリが返した 500) |
| アプリを止めたまま nginx を再起動 | nginx が起動しない | [emerg] host not found in upstream "app" |
502 は、nginx がアプリにつなげなかったか、つないだのに正しい返事が返ってこなかったときです。504 は、nginx が決めた時間までに返事が来なかったときです。
どちらの場合も、nginx のエラーログに理由が1行で出ます。まずはその1行を見つけるところから始めます。
まずエラーログを見る
ブラウザに出る「502 Bad Gateway」の画面には、原因は書かれていません。理由は nginx のエラーログにだけ出ます。
エラーログの場所(apt 版と Docker 版)
apt で入れた nginx なら、エラーログは既定で /var/log/nginx/error.log です。
Docker の公式イメージの nginx は、ログをファイルではなく標準出力・標準エラーに出すので、docker compose logs で見ます。
# apt で入れた nginx
sudo tail -n 50 /var/log/nginx/error.log
# Docker の nginx(サービス名が nginx の場合)
docker compose logs --tail 50 nginx
アクセスログに upstream_status と応答時間を出す
エラーログと合わせて、アクセスログに転送先の情報を出しておくと切り分けが早くなります。実験では次の log_format にしました。
log_format main '"$request" $status upstream=$upstream_addr '
'upstream_status=$upstream_status '
'upstream_response_time=$upstream_response_time rt=$request_time';
access_log /dev/stdout main;
error_log /dev/stderr warn;| 変数 | 分かること |
|---|---|
$upstream_addr | 実際に転送した宛先(名前を引いたあとの IP とポート) |
$upstream_status | アプリが返したステータス。nginx がつなげなかったときは 502・504 になる |
$upstream_response_time | アプリを待った秒数 |
$request_time | リクエスト全体にかかった秒数 |
僕の VPS の nginx も、アクセスログを1行1つの JSON で出していて、$upstream_status と $upstream_response_time を入れています。
待った秒数が分かると、504 なら「何秒で切られたか」、502 なら「すぐ断られたのか、しばらく待ってから失敗したのか」が分かります。
502 の原因と直し方
502 は、エラーログの文言で原因が分かれます。実験で出た3つと、アプリ側のエラーが 502 に見える場合を順に見ます。
原因①:アプリが止まっている・起動している途中
よくあるのは、アプリがまだ動いていないときです。
Docker Compose の記事を書いたときも、docker compose restart web の直後に curl で開くと 502 Bad Gateway が返りました。
アプリが起動し直している数秒の間に、リクエストが届いたためと考えています。

今回の実験で docker compose stop app でアプリを止めると、1回目は 60秒待って 504、2回目は 14秒ほどで 502 になりました。502 のときのエラーログは次の行です。
connect() failed (113: Host is unreachable) while connecting to upstream, client: 172.18.0.1, server: , request: "GET /hello HTTP/1.1", upstream: "http://172.18.0.3:8000/hello", host: "127.0.0.1:18081"この秒数とエラー番号は、僕の手元の Mac の Docker Desktop での結果です。Linux の VPS で同じになるとは限りません。止まったアプリへの接続は、502 にも 504 にもなると考えてください。
直し方は、アプリの状態とログを見て、起こすことです。
docker compose ps
docker compose logs --tail 50 app
docker compose start app再起動の直後だけ出る 502 なら、起動が終われば消えます。ずっと続くなら、アプリのログに起動時のエラーが出ていないかを見ます。
原因②:転送先のポートや名前の誤り
proxy_pass のポートを間違えると、すぐに 502 になります。実験ではアプリが 8000番で待っているところへ、8001番に転送しました。
location /wrongport/ {
proxy_pass http://app:8001;
}返事は 0.001秒ほどで返り、エラーログには次の行が出ました。
connect() failed (111: Connection refused) while connecting to upstream, client: 172.18.0.1, server: , request: "GET /wrongport/x HTTP/1.1", upstream: "http://172.18.0.3:8001/wrongport/x", host: "127.0.0.1:18081"111: Connection refused は、相手のマシンには届いたが、そのポートで誰も待っていなかったという意味です。upstream: の宛先とポートが、アプリの待ち受け先と合っているかを見ます。
名前(サービス名など)を間違えた場合は、502 ではなく、nginx の起動時に host not found で止まります。後の章で詳しく書きます。
Docker の nginx で 127.0.0.1 へ転送したときも、同じ 111 の 502 になります。コンテナの中の 127.0.0.1 は nginx 自身を指すためです。

原因③:アプリが返事をせずに接続を切る
つながったのに、アプリが何も返さずに接続を切った場合も 502 です。実験では、リクエストを読んだら切るだけのサーバーへ転送しました。
upstream prematurely closed connection while reading response header from upstream, client: 172.18.0.1, server: , request: "GET /crash/x HTTP/1.1", upstream: "http://172.18.0.2:9000/crash/x", host: "127.0.0.1:18081"prematurely closed は「返事の途中(ここでは返事の頭)で切られた」という意味です。接続まではできているので、名前やポートは合っています。
調べるのはアプリ側です。処理中にプロセスが落ちていないか、アプリのログを見ます。一般には、メモリ不足でプロセスが強制終了されたときにも、この形になることがあります。
原因④:アプリ側のエラーが 502 に見える
nginx のエラーログに何も出ていないのに 502 になることがあります。このときは、nginx ではなくアプリが 502 を返しています。
僕も VPS にアプリを載せたとき、アプリが返す 502 に迷いました。
Next.js から Django の API を呼ぶ部分が 502 になっていましたが、たどると Django が Host ヘッダーを 400 で断っていました。
Next.js が裏の API の失敗を受けて、自分で 502 を返していたわけです。nginx から見れば、アプリが返した 502 をそのまま渡すだけです。

見分け方は、エラーログに行があるかどうかです。後で出てくる Gunicorn の 500 の実験でも、アプリが返したエラーはエラーログに出ず、アクセスログの upstream_status にだけ出ました。
502 なのにエラーログが空なら、アプリのログと、そのアプリがさらに呼んでいる先を確かめてください。
504 の原因と直し方
504 は、nginx がアプリを待つ時間の上限を超えたときに出ます。
proxy_read_timeout を超えている
アプリにつないだあと、返事を待つ時間の上限が proxy_read_timeout です。nginx の既定は 60秒です。実験では3秒にして、5秒かかる処理を呼びました。
location /short/ {
proxy_pass http://app:8000/slow;
proxy_read_timeout 3s;
}ちょうど3.0秒で 504 になり、エラーログには次の行が出ました。
upstream timed out (110: Operation timed out) while reading response header from upstream, client: 172.18.0.1, server: , request: "GET /short/?5 HTTP/1.1", upstream: "http://172.18.0.3:8000/slow?5", host: "127.0.0.1:18081"アクセスログでも upstream_response_time=3.009 で、設定した3秒で切られたことが分かります。
末尾が while reading response header なら、つながったあとに返事が遅かったということです。
while connecting to upstream なら、つなぐところで時間切れになっています。
つなぐ段階の上限は proxy_connect_timeout(既定 60秒)です。上のアプリを止めた実験の1回目は、こちらの 504 でした。
延ばす前に処理を見直す
504 が出たからといって、すぐに proxy_read_timeout を延ばすのはおすすめしません。まず、その処理がなぜ遅いのかを見ます。
ここからは一般的な考え方です。重い集計や外部 API の呼び出しを、リクエストの中で待っていないかを確かめます。時間がかかる処理は、裏で動かして結果を後で見せる形にすると、タイムアウトの心配がなくなります。
どうしても延ばすなら、全体ではなく、遅い処理の location だけにします。上の例のように location の中に書けば、その location にだけ効きます。
Gunicorn の timeout を超えると 502 ではなく 500 になった
Gunicorn には、1つのリクエストにかけられる時間の上限 --timeout があります。超えると、Gunicorn がワーカーを止めて起動し直します。
この場合は 502 になると説明されることが多いのですが、手元で試すと結果は違いました。--timeout 10 にして、15秒かかる処理を呼んだ結果です。
status=500 time=11.955206s
"GET /slow?15 HTTP/1.1" 500 upstream=172.18.0.3:8000 upstream_status=500 upstream_response_time=11.953 rt=11.953ステータスは 500 で、nginx のエラーログには何も出ませんでした。アクセスログの upstream_status=500 から、アプリ側が 500 を返したことが分かります。
Gunicorn のログの最後の4行は次のとおりです。
sys.exit(1)
SystemExit: 1
[2026-11-19 06:05:02 +0000] [11] [INFO] Worker exiting (pid: 11)
[2026-11-19 06:05:02 +0000] [12] [INFO] Booting worker with pid: 12ワーカーが終了し、新しいワーカーが起動しています。nginx の proxy_read_timeout(既定 60秒)より先に、Gunicorn の10秒の上限に当たったので、Gunicorn 側で終わったわけです。
つまり、遅い処理で何が返るかは、nginx と Gunicorn のどちらの上限が短いかで決まります。
| 上限の関係 | 遅い処理で返るもの | 見る場所 |
|---|---|---|
| Gunicorn の timeout が短い | 500(今回の結果) | Gunicorn のログ、アクセスログの upstream_status |
| nginx の proxy_read_timeout が短い | 504 | nginx のエラーログの upstream timed out |
処理の時間を延ばすなら、両方をそろえて見直します。片方だけ延ばしても、もう片方の上限で切られます。
500 が出たら、アプリのバグだけでなく、Gunicorn のログに Worker exiting が出ていないかも見てください。
アプリを止めたまま nginx を起動すると、nginx が起動しない
Docker Compose で、転送先をサービス名で書いているときの話です。アプリが止まっていると、nginx は起動時に名前を引けず、起動に失敗します。
nginx -t と reload は失敗し、古い設定のまま動き続ける
アプリを止めた状態で、nginx のコンテナの中で nginx -t を実行しました。
nginx: [emerg] host not found in upstream "app" in /etc/nginx/nginx.conf:8
nginx: configuration file /etc/nginx/nginx.conf test failed設定ファイルは書き換えていないのに、テストが失敗します。nginx は設定を読むときに、proxy_pass の名前を引いているためです。
nginx -s reload も同じエラーで失敗しました。ただ、動いていた nginx は止まらず、古い設定のまま動き続けました。
設定を直して reload したつもりでも、反映されていないことがあります。reload の後は、エラーが出ていないか必ずログを見てください。
nginx を再起動すると起動しない
アプリを止めたまま docker compose restart nginx を実行すると、nginx は同じ [emerg] host not found in upstream で起動しませんでした。
こうなると、アプリと関係のないサイトや静的ファイルまで、すべて表示できなくなります。1つの nginx で複数のサイトを受けている構成では影響が大きいです。
アプリを起動してから nginx を起動し直すと、元どおり 200 になりました。順番を守れば直ります。
resolver と変数で書くと、アプリが止まっていても起動する
名前をリクエストのたびに引く書き方にすると、起動時に名前を引かなくなります。
server {
listen 80;
resolver 127.0.0.11 valid=10s;
location / {
set $up app:8000;
proxy_pass http://$up;
}
}127.0.0.11 は、Docker のネットワークの中で名前を答えてくれる DNS です。proxy_pass に変数を使うと、nginx は起動時ではなく、リクエストのときにこの DNS で名前を引きます。
この設定で、アプリを止めたまま nginx を再起動すると、nginx は起動しました。リクエストは 502 になり、エラーログは次の行です。
app could not be resolved (3: Host not found), client: 172.18.0.1, server: , request: "GET /hello HTTP/1.1", host: "127.0.0.1:18081"そのあとアプリを起動すると、nginx には何もしないまま 200 が返りました。
僕の VPS では resolver を使っていない
僕の VPS の nginx.conf は、proxy_pass にサービス名をそのまま書いていて、resolver は使っていません。
つまり、アプリを止めたまま nginx を作り直すと、今回の実験と同じことが起きうる書き方です。
変数なしの書き方には、名前の書き間違いに起動時に気づけるという良さもあります。resolver を使うと、間違いがリクエストのときの 502 まで見えません。
どちらを選ぶにしても、nginx を起動し直す前に、アプリのコンテナが動いているかを docker compose ps で確かめると安全です。
直したあとに確かめる
設定やアプリを直したら、次の順で確かめます。
nginx -tで設定を確かめる(Docker ならdocker compose exec nginx nginx -t)- reload したら、エラーログに emerg や error が出ていないかを見る
- curl でステータスと時間を確かめる
- アクセスログの upstream_status と upstream_response_time を見る
curl -s -o /dev/null -w 'status=%{http_code} time=%{time_total}s\n' http://127.0.0.1:18081/hello-w でステータスと時間だけを出すと、502 がすぐ返るのか、何秒か待って返るのかが分かります。
過去のログから 502・504 の行だけを拾うときは、grep が便利です。
sudo grep -E '" (502|504) ' /var/log/nginx/access.log | tail -n 20
sudo grep -E 'upstream|emerg' /var/log/nginx/error.log | tail -n 20
ログを前後まで読みたいときは less で開くと、検索しながら読めます。

よくある質問
503 Service Unavailable とは何が違いますか?
ここは一般論です。503 は「いまは受け付けられない」という意味で、アプリがメンテナンス中に自分で返すほか、nginx でアクセス数を制限する limit_req の既定の返事も 503 です。
502・504 のように、アプリとのやりとりが失敗したときのエラーではありません。503 が出たら、アプリのメンテナンス表示と、nginx の制限の設定を見てください。
502 がたまにだけ出ます。
アクセスログで、502 が出た時刻を見てください。デプロイやコンテナの再起動の時刻と重なっていれば、起動の途中にリクエストが届いた可能性が高いです。
時刻がばらばらなら、エラーログの文言を見て、アプリが落ちていないか(prematurely closed)を確かめます。
アプリのコンテナを作り直したら、nginx の reload は要りますか?
今回の実験では、docker compose up -d --force-recreate app で作り直しても IP は変わらず、nginx はそのまま 200 を返しました。
IP が変わる場合があるかは試していません。変数なしの proxy_pass では、nginx は起動時に引いた IP を使い続けるので、作り直しの後に 502 が続くなら、nginx を reload してください。
proxy_read_timeout を延ばしたのに 504 が続きます。
書いた location に、そのリクエストが本当に当たっているかを確かめます。別の location に当たっていると、延ばした値は効きません。
エラーログの末尾が while connecting なら、延ばすべきなのは proxy_connect_timeout です。そもそもアプリにつながっていないので、アプリの状態を先に見てください。
まとめ:エラーログの1行から原因をたどる
- 502 は返事がおかしい、504 は待ちきれなかった。理由は nginx のエラーログに1行で出る
- 111: Connection refused はポートや宛先の誤り、prematurely closed はアプリが途中で切った
- エラーログが空の 502・500 は、アプリが返したもの。アクセスログの upstream_status で分かる
- upstream timed out は proxy_read_timeout(既定 60秒)超え。延ばす前に処理を見直す
- Gunicorn の timeout を超えた処理は、僕の環境では 502 ではなく 500 になった
- アプリを止めたまま nginx を起動すると、host not found で nginx が起動しない。reload は失敗して古い設定のまま動く
- resolver と変数で書けば、アプリが止まっていても nginx は起動する
502・504 が出たら、まずエラーログの末尾を見て、上の表のどれに当たるかを確かめてください。
VPS を借りてから nginx でサイトを公開し、Docker で運用するまでの流れは、こちらにまとめています。

