nginxの502 Bad Gateway・504の原因と直し方|ログで切り分け

  • 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 からアプリへ転送する設定そのものは、こちらの記事で書いています。

項目内容
nginxnginx 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)
この記事の環境(2026年11月19日に確認)

結論:502 は「返事がおかしい」、504 は「待ちきれなかった」

先に、実験の結果をまとめます。

状況ステータスエラーログ(要点)
転送先のポートの誤り502connect() failed (111: Connection refused)
アプリが返事をせずに切る502upstream prematurely closed connection
proxy_read_timeout(3秒)を超える処理504upstream timed out (110: ...) while reading response header
Gunicorn の timeout(10秒)を超える処理500出ない(アプリが返した 500)
アプリを止めたまま nginx を再起動nginx が起動しない[emerg] host not found in upstream "app"
502・504 の再現結果(nginx 1.30.6、Gunicorn 23.0.0)

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 で見ます。

ShellScript
# apt で入れた nginx
sudo tail -n 50 /var/log/nginx/error.log

# Docker の nginx(サービス名が nginx の場合)
docker compose logs --tail 50 nginx

apt 版の場所は一般的な既定値です。設定で変えていることもあるので、error_log の行で確かめてください。設定ファイルの場所は、こちらにまとめています。

アクセスログに upstream_status と応答時間を出す

エラーログと合わせて、アクセスログに転送先の情報を出しておくと切り分けが早くなります。実験では次の log_format にしました。

Nginx
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 のときのエラーログは次の行です。

Plaintext
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 にもなると考えてください。

直し方は、アプリの状態とログを見て、起こすことです。

ShellScript
docker compose ps
docker compose logs --tail 50 app
docker compose start app

再起動の直後だけ出る 502 なら、起動が終われば消えます。ずっと続くなら、アプリのログに起動時のエラーが出ていないかを見ます。

原因②:転送先のポートや名前の誤り

proxy_pass のポートを間違えると、すぐに 502 になります。実験ではアプリが 8000番で待っているところへ、8001番に転送しました。

Nginx
location /wrongport/ {
    proxy_pass http://app:8001;
}

返事は 0.001秒ほどで返り、エラーログには次の行が出ました。

Plaintext
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 自身を指すためです。

Gunicorn をソケットファイルで動かしている場合は、upstream: が unix: で始まるパスになります。今回はソケットでは試していません。一般的には、ファイルの場所と権限を確かめます。

原因③:アプリが返事をせずに接続を切る

つながったのに、アプリが何も返さずに接続を切った場合も 502 です。実験では、リクエストを読んだら切るだけのサーバーへ転送しました。

Plaintext
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秒かかる処理を呼びました。

Nginx
location /short/ {
    proxy_pass http://app:8000/slow;
    proxy_read_timeout 3s;
}

ちょうど3.0秒で 504 になり、エラーログには次の行が出ました。

Plaintext
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秒かかる処理を呼んだ結果です。

Plaintext
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行は次のとおりです。

Plaintext
    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 側で終わったわけです。

試したのは Gunicorn 23.0.0 の同期ワーカー(既定の sync)だけです。ほかのバージョンやワーカーの種類で同じになるかは確かめていません。

つまり、遅い処理で何が返るかは、nginx と Gunicorn のどちらの上限が短いかで決まります。

上限の関係遅い処理で返るもの見る場所
Gunicorn の timeout が短い500(今回の結果)Gunicorn のログ、アクセスログの upstream_status
nginx の proxy_read_timeout が短い504nginx のエラーログの upstream timed out
Gunicorn と nginx の上限の関係

処理の時間を延ばすなら、両方をそろえて見直します。片方だけ延ばしても、もう片方の上限で切られます。

500 が出たら、アプリのバグだけでなく、Gunicorn のログに Worker exiting が出ていないかも見てください。

アプリを止めたまま nginx を起動すると、nginx が起動しない

Docker Compose で、転送先をサービス名で書いているときの話です。アプリが止まっていると、nginx は起動時に名前を引けず、起動に失敗します。

nginx -t と reload は失敗し、古い設定のまま動き続ける

アプリを止めた状態で、nginx のコンテナの中で nginx -t を実行しました。

Plaintext
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 と変数で書くと、アプリが止まっていても起動する

名前をリクエストのたびに引く書き方にすると、起動時に名前を引かなくなります。

Nginx
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 になり、エラーログは次の行です。

Plaintext
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 が返りました。

一般的な注意点として、proxy_pass に変数を使うと、末尾の / でパスを置き換える動きが変数なしのときと変わります。パスを置き換えている location に使うときは、アプリに届くパスを確かめてください。

僕の VPS では resolver を使っていない

僕の VPS の nginx.conf は、proxy_pass にサービス名をそのまま書いていて、resolver は使っていません。

つまり、アプリを止めたまま nginx を作り直すと、今回の実験と同じことが起きうる書き方です。

変数なしの書き方には、名前の書き間違いに起動時に気づけるという良さもあります。resolver を使うと、間違いがリクエストのときの 502 まで見えません。

どちらを選ぶにしても、nginx を起動し直す前に、アプリのコンテナが動いているかを docker compose ps で確かめると安全です。

直したあとに確かめる

設定やアプリを直したら、次の順で確かめます。

直したあとの確認
  1. nginx -t で設定を確かめる(Docker なら docker compose exec nginx nginx -t)
  2. reload したら、エラーログに emerg や error が出ていないかを見る
  3. curl でステータスと時間を確かめる
  4. アクセスログの upstream_status と upstream_response_time を見る
ShellScript
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 が便利です。

ShellScript
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 で運用するまでの流れは、こちらにまとめています。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

この記事を書いた人

普段は主にPython開発をしています。
最近はAI駆動開発にも関わっています。