できない.dev

nginx「504 Gateway Time-out」の原因と直し方

504 Gateway Time-out は、転送先の処理を 60 秒以内に返すか、proxy_read_timeout を延ばせば直る。
nginx が転送先の応答を待ちきれないと返し、error.log には upstream timed out が出る。

公開: 更新:

症状できない
curl -s -w '%{http_code} %{time_total}s\n' http://127.0.0.1/slow/
…
504 60.060893s

2026-11-18 に nginx:1.27 で実際に打って取った出力。検証環境の詳細

要約

nginx をリバースプロキシにしたページで、ちょうど 60 秒待たされたあとに次のページが返る。

<html>
<head><title>504 Gateway Time-out</title></head>
<body>
<center><h1>504 Gateway Time-out</h1></center>
<hr><center>nginx/1.31.8</center>
</body>
</html>

504 Gateway Time-out は、nginx が転送先(upstream)の応答を待ちきれずに打ち切ったときの応答である。
転送先の処理を 60 秒以内に返すか、proxy_read_timeout を延ばせば直る。
nginx 1.31.8 の公式イメージで、75 秒かけて応答するアプリの前に置くと、error.log には次の行が出た。

[error] 21#21: *1 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 172.21.0.1, server: , request: "GET /slow/ HTTP/1.1", upstream: "http://172.21.0.2:8000/", host: "127.0.0.1:18504"

while の後ろが、どの段階で待ちきれなかったかを示す。

実行例

nginx:1.27 のコンテナで 65 秒待ってから応答する転送先を proxy_pass すると、既定の待ち時間 60 秒で 504 が返り、error.log に upstream timed out (110: Connection timed out) が残った。
その location に proxy_read_timeout 120s を書いて reload すると、同じ転送先が 200 を返した。

$ curl -s -w '%{http_code} %{time_total}s\n' http://127.0.0.1/slow/
<html>
<head><title>504 Gateway Time-out</title></head>
<body>
<center><h1>504 Gateway Time-out</h1></center>
<hr><center>nginx/1.27.5</center>
</body>
</html>
504 60.060893s
$ grep -o "upstream timed out.*while reading response header from upstream" error.log
upstream timed out (110: Connection timed out) while reading response header from upstream
$ nginx -p . -c nginx.conf -t
nginx: the configuration file ./nginx.conf syntax is ok
nginx: configuration file ./nginx.conf test is successful
$ nginx -p . -c nginx.conf -s reload
2026/11/17 20:00:57 [notice] 26#26: signal process started
$ curl -s -w '%{http_code} %{time_total}s\n' http://127.0.0.1/slow-fixed/
ok
200 65.001777s

— 2026-11-18 時点の出力

検証環境2026-11-18 検証
検証日
実行環境
nginx:1.27 Debian GNU/Linux 12 (bookworm)

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 処理を短くするか、待つ時間を延ばす

時間のかかる処理(集計・外部 API の呼び出し・大きなファイルの生成)は、ジョブとして裏で動かし、すぐに応答を返す形にする。
どうしても待つ必要があるパスだけ、location で上限を延ばす。

location /slow-fixed/ {
    proxy_pass http://slow:8000/;
    proxy_read_timeout 120s;
}

nginx -t で設定を確かめてから nginx -s reload で読み込み直す。
この location では、75 秒かかる同じアプリが 200 を返した。
http や server に書くと全部のパスに効き、止まった転送先を長く待つことになる。

2. 接続先を確かめる

while connecting to upstream のときは、ログの upstream: に出たアドレスへ、nginx と同じコンテナやサーバーから接続してみる。

curl -v http://172.21.0.2:8000/

届かなければ、proxy_pass の宛先・ファイアウォール・Docker のネットワークを直す。
proxy_connect_timeout を延ばしても、届かない宛先には接続できない。

3. FastCGI では fastcgi_read_timeout を延ばす

fastcgi_pass を書いている location に、次の 1 行を足して reload する(ngx_http_fastcgi_module(新しいタブで開く))。

fastcgi_read_timeout 120s;

proxy_read_timeout を書き足しても、FastCGI へ渡す location の待ち時間は変わらない。

よくある原因

  1. 転送先の処理が長い。
    while reading response header from upstream は、接続はできたが応答ヘッダが届かなかったことを示す。
    待つ上限は proxy_read_timeout で、既定は 60 秒である(ngx_http_proxy_module(新しいタブで開く))。
    この上限は、読み取りと読み取りの間隔に掛かる。
    15 秒ごとに 1 行ずつ返すアプリは、合計 75 秒かかっても 200 で最後まで届いた。
  2. 転送先に接続できない。
    ファイアウォールがパケットを黙って捨てる宛先のように、応答の無いアドレスへ proxy_pass すると、while connecting to upstream の 504 になった。
    同じネットワークの空きアドレスは No route to host、接続を断る宛先は Connection refused の 502 になる。
    接続を待つ上限は proxy_connect_timeout で、既定は 60 秒である。
    公式ドキュメントは、この値は通常 75 秒を超えられないと書いている。
  3. FastCGI の待ち時間を超えている。
    PHP-FPM のように fastcgi_pass で渡す場合に効くのは、fastcgi_read_timeout(既定 60 秒)である。
    FastCGI の 504 はここでは起こしていない。

転送先が止まっていて接続をすぐに断られるときは、504 より先に 502 が返る。