Nginx

冒頭まとめ Nginx で 429 Too Many Requests に出会ったとき、最初に押さえるべき事実があります。Nginx はレート制限の拒否に、既定で 429 を使いません。 公式文書を見ると、頻度を制限する仕組みの応答コードは limit_req_status で指定し、その既定値は 503 です。同時接続数を制限する仕組みも同様で、limit_conn_status の既定値はやはり 503 です。実装を読んでも、どちらも既定値として「サービス利用不可」を表す定数が設定されています。 つまり、Nginx が返した 429 には次のいずれかの理由があります。誰かが limit_req_status 429 または limit_conn_status 429 を明示的に設定した。上流のアプリケーションが返した 429 を、Nginx がそのまま中継している。あるいは、Nginx より前段の仕組みが返している。 逆方向の混乱もよく起きます。「429 を返すよう設定したのに 503 のままだ」という状況です。これは多くの場合、頻度の制限と接続数の制限が別々の設定であることを見落としているために起こります。片方だけ 429 にしても、もう片方が発動していれば 503 が返ります。 もう1つ、実務で効く事実があります。Nginx はレート制限で拒否するとき、待つべき時間を示すヘッダーを付けません。実装を確認しても、頻度と接続数のどちらの仕組みにも該当する記述はありません。429 に設定したとしても、クライアントは「いつ再試行してよいか」を知る手段がないままです。 エラーの概要 まず、既定の設定でレート制限に当たった場合の記録です。応答は 503 ですが、記録の文言は制限によるものだと分かる形になっています。 2026/08/03 12:00:00 [error] 1234#1234: *56 limiting requests, excess: 0.622 by zone "one", client: 203.0.113.10, server: example.com, request: "GET /search/ HTTP/1.1" limiting requests が頻度の制限、limiting connections が接続数の制限です。どのゾーンで拒否されたかも同じ行に出ます。この文言は応答コードを 429 に変えても変わりません。記録の文言と応答コードは独立している、と押さえてください。 ...

冒頭まとめ アクセスログに残る 499 は、Nginx が応答を返す前にクライアント側から接続が切られたことを示すコードです。HTTP の標準にはない Nginx 独自のコードで、相手はすでにいないため、利用者のブラウザにこのコードが表示されることはありません。つまり 499 は「エラー画面が出る問題」ではなく「ログにだけ現れる兆候」です。 原因は、クライアントが先に諦めた理由が何か、という問いに置き換えられます。典型は3つで、上流の応答が遅くクライアント側の制限時間が先に切れた、利用者が操作を中断した（画面を閉じた・再読み込みした）、Nginx の手前にいる中継役（ロードバランサーなど）や監視の仕組みが応答を待たずに切断した、のいずれかです。切り分けの鍵は処理時間の記録ですが、既定のログ形式には含まれないため、まず $request_time をログに加えるところから始めます。 エラーの概要 Nginx のソースコードには、499 を定義した箇所に説明が書かれています。要約すると、リクエストの処理中にクライアントが接続を閉じた場合を表すコードが HTTP には定義されていないため、応答ヘッダーを送ろうとする前にクライアントが接続を閉じていた状況を記録する目的で、独自のコードとして導入した、という内容です。 504 Gateway Timeout との対比で理解すると分かりやすいコードです。上流の応答が遅いとき、Nginx 側が待ちきれずに打ち切ればクライアントに 504 が返ります。Nginx がまだ待っている間にクライアント側が先に切れば、誰にも何も返らず、ログに 499 が残ります。同じ「遅い」という状況でも、どちらが先に諦めたかで記録が変わります。 診断上の重要な特徴が2つあります。第一に、499 はエラーログには info レベルでしか記録されません。エラーログの既定のレベルでは何も出力されないため、「アクセスログに 499 があるのにエラーログに手がかりがない」のは正常な動作です。第二に、既定では、クライアントの切断を検知した時点で Nginx は上流への接続も閉じます（この動作は後述の proxy_ignore_client_abort で変えられます）。ただし上流のアプリケーションが切断を検知しない作りの場合、応答の届け先がないまま処理だけが完走することもあります。 アクセスログには次のように記録されます。応答を送っていないため、送信バイト数が 0 になるのが典型です。 192.168.1.100 - - [09/Jul/2026:14:22:10 +0900] "POST /api/report HTTP/1.1" 499 0 "-" "python-requests/2.31.0" まず最初に：処理時間をログに出す 既定の combined 形式には、リクエストの処理にかかった時間が含まれません。499 の切り分けには時間の情報が不可欠なので、log_format に $request_time（リクエスト全体の処理時間）と $upstream_response_time（上流の応答にかかった時間）を加えます。どちらも公式ドキュメントに記載のある変数です。 http { log_format timed '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" "$http_user_agent" ' 'rt=$request_time urt=$upstream_response_time'; access_log /var/log/nginx/access.log timed; } 反映後に記録される 499 の行を見て、次のように読み分けます。 ...

冒頭まとめ Nginx の 413 Request Entity Too Large は、リクエスト本文の大きさが client_max_body_size の上限を超えたときに返されます。上限の既定値は 1MB と小さいため、ファイルのアップロード機能を作ると最初にぶつかりやすいエラーです。対処はほぼ client_max_body_size の調整に集約されますが、落とし穴が2つあります。1つは設定を書く場所で、より内側（location など）に別の指定があるとそちらが使われるため、書いたのに効かないという状況が起きます。もう1つは Nginx の先にいるアプリケーション側の上限で、Nginx の上限を上げるだけでは足りない場合があります。 必要な上限の値は推測しなくて済みます。Nginx が413を返したとき、エラーログに実際に送られようとしたバイト数が記録されるからです。まずエラーログを読み、実測値をもとに上限を決めます。 エラーの概要 413 は、リクエストの本文（ファイルのアップロード内容やフォームの送信内容）が、サーバーの受け入れ上限を超えたことを示すコードです。Nginx では client_max_body_size がこの上限を定めており、公式ドキュメントのとおり既定値は 1m（1MB）です。なお、HTTP の現行仕様（RFC 9110）ではこのコードの名称は Content Too Large に改められていますが、Nginx の既定エラーページの文言は「413 Request Entity Too Large」です。 注意すべき点として、公式ドキュメントには、ブラウザはこのエラーを正しく表示できない場合があるという注記があります。つまり利用者の画面では、413のページが出るとは限らず、送信が途中で失敗した・接続が切れた、といった413と分からない形で現れることがあります。アップロードだけが原因不明で失敗するという相談を受けたら、まずサーバー側のログで413が出ていないかを確認する価値があります。 アクセスログ（既定の combined 形式）には次のように記録されます。 192.168.1.100 - - [08/Jul/2026:11:20:15 +0900] "POST /upload HTTP/1.1" 413 183 "-" "Mozilla/5.0" まず最初に：エラーログを読む アクセスログで413を確認したら、同時刻のエラーログを見ます。 sudo grep "too large" /var/log/nginx/error.log | tail -10 client intended to send too large body: 15728640 bytes のような行があれば、Nginx 自身が client_max_body_size の検査で拒否しています。行末の数字が、実際に送られようとした本文のバイト数です（この例では15MB）。必要な上限をこの実測値から決められるので、原因1・2に進みます。チャンク転送（本文の大きさを事前に知らせない送り方）の場合は client intended to send too large chunked body という文言になります。 ...

冒頭まとめ Nginx の 502 Bad Gateway は、リバースプロキシとしての Nginx が上流（proxy_pass や fastcgi_pass の接続先）への接続に失敗したか、接続はできたものの応答として解釈できないデータを受け取ったことを示します。原因はほぼ確実にエラーログの文言で特定できます。connect() failed (111: Connection refused) なら上流が起動していないか接続先の指定違い、unix ソケットへの (2: No such file or directory) や (13: Permission denied) ならソケットのパスか権限、no live upstreams なら全上流サーバーの一時除外、upstream prematurely closed connection なら上流の応答途中の切断、upstream sent too big header なら応答ヘッダーのバッファ超過、SSL_do_handshake() failed なら上流との TLS ハンドシェイク失敗です。 502と誤解されやすい隣のコードも押さえておくと迷いません。上流の応答待ちの時間切れは502ではなく504です（エラーログに upstream timed out と残ります）。limit_req などの制限超過は503、応答前にクライアント側が切断した場合はアクセスログに499が残ります。「遅いから502」という説明を見かけますが、Nginx のソースコード上、時間切れは504に明示的に割り当てられており、502になるのはそれ以外の接続失敗と不正応答です。 エラーの概要 Nginx は上流への中継に失敗したとき、失敗の種類ごとに返すステータスコードを割り当てます。この割り当てはソースコード（ngx_http_upstream.c の ngx_http_upstream_next）で確認でき、時間切れ（NGX_HTTP_UPSTREAM_FT_TIMEOUT）は504、接続失敗・不正な応答ヘッダー・全サーバー除外などそれ以外の失敗は既定の分岐として502になります。つまり502は「時間内に、しかし正常には、上流とやり取りできなかった」ことの総称です。 ブラウザに表示されるデフォルトのエラーページ： 502 Bad Gateway nginx アクセスログの出力例： 192.0.2.10 - - [15/Jul/2026:10:23:45 +0900] "GET /api/users HTTP/1.1" 502 157 "-" "Mozilla/5.0" エラーログ（/var/log/nginx/error.log）の出力例。この upstream: に続く接続先と、括弧内の失敗理由が切り分けの起点です： ...

冒頭まとめ Nginx の 503 Service Unavailable の原因は、ほぼ次の3系統のいずれかです。第一に、limit_req（リクエスト頻度の制限）や limit_conn（同時接続数の制限）の超過で、Nginx 自身が既定で 503 を返します。第二に、メンテナンス用に設定した return 503 が設定内に残っているケースです。第三に、proxy_pass 先の上流アプリケーション自身が 503 を返し、Nginx がそれをそのまま中継しているケースです。 注意すべき点として、「バックエンドに接続できない」ときに Nginx が返すのは 503 ではなく 502 Bad Gateway、応答待ちで時間切れになったときは 504 Gateway Timeout です。503 の調査だと思っていたものが実は 502 や 504 の問題だった、ということが起こりやすいので、まずアクセスログで実際のステータスコードを確かめ、次にエラーログの文言で原因を絞り込みます。 エラーの概要 503 Service Unavailable は、サーバーが一時的にリクエストを処理できない状態を示します。Nginx をリバースプロキシとして使っている場合、似た状況で返るコードが3つあり、区別が重要です。上流への接続自体に失敗した場合（プロセス停止、ポート違い、接続拒否など）は 502、接続はできたが応答が時間内に返らなかった場合は 504、そして上流が「処理できない」と自ら 503 を応答した場合はその 503 がそのまま中継されます。加えて、上流と無関係に Nginx 自身が制限機能によって 503 を返す場合があります。 Nginx が自身の既定ページで 503 を返す場合、ブラウザには「503 Service Temporarily Unavailable」という見出しだけが表示されます。「The server is temporarily unable to service your request due to maintenance downtime or capacity problems.」のような説明文が表示されているなら、それは Nginx の既定ページの文言ではなく、上流の別のサーバーが生成した 503 を中継している可能性が高いです（原因3）。 ...

冒頭まとめ Nginx の 504 Gateway Time-out は、リバースプロキシとして上流（proxy_pass や fastcgi_pass の先）の応答を待ったが、時間内に届かなかったことを示します。時間切れになるタイマーは2つあり、どちらかはエラーログの文言で判別できます。文言が while connecting to upstream で終わっていれば、接続の確立自体が時間切れです（proxy_connect_timeout。原因は経路の問題が典型）。while reading response header from upstream で終わっていれば、接続はできたが応答が返らない時間切れです（proxy_read_timeout。原因は上流の処理の遅さが典型）。 対処の本筋は、時間を延ばすことではなく、どのタイマーがなぜ切れたかを特定することです。応答待ちの時間切れなら遅い処理の改善が本筋で、正当に時間のかかる処理に限ってタイムアウトを延ばします。その際、設定したのに効かないという定番の落とし穴（別の location が処理している、リロード漏れ）があるため、実効設定の確認までを対処に含めます。 エラーの概要 Nginx が自身の既定ページで504を返す場合、ブラウザには「504 Gateway Time-out」（Time-out はハイフン入り）という見出しだけが表示されます。エラーログには次のように記録されます。 2026/07/14 14:32:10 [error] 1234#1234: *567 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 192.168.1.100, server: example.com, request: "GET /api/report HTTP/1.1", upstream: "http://127.0.0.1:8080/api/report" 関係するタイマーの正確な仕様を押さえておくと、対処を誤りません。公式ドキュメントによると、proxy_connect_timeout（既定60秒）は上流との接続確立に対する制限で、通常75秒を超える値には設定できません。proxy_read_timeout（既定60秒）は応答の読み取りに対する制限ですが、応答全体の転送時間の上限ではなく、連続する2つの読み取り操作の間隔に適用されます。つまり上流が少しずつでもデータを送り続けていれば、全体が60秒を超えても切れません。切れるのは「この時間、何も送られてこなかった」ときです。proxy_send_timeout（既定60秒）は同様に、上流への書き込み操作の間隔に適用されます。PHP-FPM などの FastCGI 構成では、対応する fastcgi_read_timeout などが同じ意味を持ちます。 なお、似た状況で別のコードになる場合があります。上流への接続が即座に拒否された場合（プロセス停止・ポート違い）は504ではなく502です。また、Nginx が待っている間にクライアント側が先に諦めて切断した場合は、誰にも何も返らず、アクセスログに499が記録されます。 まず最初に：エラーログの文言でタイマーを特定する sudo grep "upstream timed out" /var/log/nginx/error.log | tail -10 該当行の末尾近くの文言を読みます。while connecting to upstream なら接続確立の時間切れで、調べるのは経路です（原因2）。while reading response header from upstream なら応答待ちの時間切れで、調べるのは上流の処理時間です（原因1）。 ...

エラーの概要 Nginx における 400 エラーは、クライアントから送信されたリクエストが HTTP 仕様に違反していることを示します。リクエストヘッダーの形式が不正、サイズ超過、または URI の不正な文字エンコーディングなどが原因となり、サーバー側で処理できない状態を意味します。本エラーはクライアント側の問題であるため、サーバー設定とリクエスト内容の両面から原因特定が必要です。 実際のエラーメッセージ例 Nginx のアクセスログに記録される 400 エラーの典型的な出力は以下の通りです。 192.168.1.100 - - [15/Nov/2024:10:23:45 +0900] "GET /api/v1/users?name=<invalid_char> HTTP/1.1" 400 157 "-" "Mozilla/5.0" また、Nginx のエラーログには以下のように記録されることがあります。 2024/11/15 10:23:45 [info] 12345#12345: *1 client sent invalid request line: "GET /search?q=あああ HTTP/1.1" よくある原因と解決手順 原因1：リクエストヘッダーサイズの超過 なぜ発生するか Nginx は large_client_header_buffers で設定されたサイズ制限を超えるヘッダーを受け取ると、400 エラーを返します。これはメモリ消費やバッファオーバーフロー攻撃を防ぐための保護機構です。特に Cookie やカスタムヘッダーが多い場合に発生しやすくなります。 Before（デフォルト設定での問題） # Nginx デフォルト設定 # large_client_header_buffers 4 8k; # 4個のバッファ、各8KB # このサイズでクライアントが 32KB 以上のヘッダーを送信するとエラー server { listen 80; server_name example.com; location / { proxy_pass http://backend; } } After（ヘッダーバッファサイズの拡大） ...

冒頭まとめ Nginx の 403 Forbidden は、サーバーがリクエストを理解したうえで、アクセスを拒否したときに返されます。原因はほぼ次の6つのいずれかです。ファイル権限の不足、パスの途中の親ディレクトリに実行権限がない、index ファイルがなく autoindex も無効、設定の deny ルール、SELinux/AppArmor、そして upstream(PHP-FPM など)自身が 403 を返すケースです。調査は、設定をいじる前に、まず /var/log/nginx/error.log を読むことから始めます。ログの文言が、どの原因なのかの手がかりになります。 エラーの概要 403 Forbidden は、Nginx がリクエスト自体は正しく受け取り、対象のリソースの場所も分かっているが、アクセスを拒否した状態です。認証情報が足りない 401 Unauthorized とは異なり、再認証しても解決しません。リソースが存在しない 404 Not Found とも異なります。 この違いはエラーログで明確に区別できます。404 はログに No such file or directory と記録され、403 は Permission denied や is forbidden と記録されます。アクセスログは「403 が起きた」ことだけを示し、なぜ起きたかはエラーログが示します。したがって、403 の調査は設定ファイルをいじる前に、まずエラーログを読むことから始めます。 まず最初に：エラーログを読む 原因を切り分ける前に、エラーログの該当行を確認します。 # 直近のエラーを表示 sudo tail -50 /var/log/nginx/error.log # 権限・拒否に関する行だけを抽出 sudo grep -iE "permission denied|forbidden|denied" /var/log/nginx/error.log ログの文言と原因の対応は次のとおりです。 # ファイルまたは親ディレクトリの権限不足 open() "/var/www/html/index.html" failed (13: Permission denied) # index ファイルがなく autoindex も無効 directory index of "/var/www/html/" is forbidden # upstream への接続が拒否された（SELinux でソケット接続が遮られた例） connect() to 127.0.0.1:8080 failed (13: Permission denied) while connecting to upstream この文言で、おおよその原因の見当がつきます。以下、6つの原因を、切り分けるべき順に説明します。 ...

冒頭まとめ Nginx の 404 Not Found は、リクエストされたリソースが見つからないときに返されます。原因はほぼ次の5つのいずれかです。root のパスが実際のファイル配置と合っていない、alias の末尾スラッシュの不一致でパス結合がずれている、try_files の誤設定、意図しない location ブロックがリクエストを処理している、そして proxy_pass 先のアプリケーション自身が 404 を返しているケースです。調査の分かれ道はエラーログです。/var/log/nginx/error.log に No such file or directory の行があれば Nginx 自身のパス解決の問題(原因1〜3)、なければ振り分けか上流の問題(原因4〜5)を疑います。 エラーの概要 404 Not Found は、サーバーがリクエストを受け取ったものの、対応するリソースを見つけられなかった状態です。アクセス自体を拒否された 403 Forbidden とは異なります。この2つはエラーログの文言で区別できます。404 は open() の失敗として (2: No such file or directory) と記録され、403 は (13: Permission denied) や is forbidden と記録されます。ファイルが実在しても読み取り権限がなければ、返るのは 404 ではなく 403 です。 Nginx が自身の既定ページで 404 を返す場合、ブラウザには「404 Not Found」という見出しと nginx の署名だけが表示されます。もし「The requested URL /xxx was not found on this server.」のような説明文が表示されているなら、それは Nginx の既定ページの文言ではありません。上流の別のサーバーやアプリケーションが生成した 404 をそのまま中継している可能性が高く、これ自体が切り分けの手がかりになります(原因5)。 ...

冒頭まとめ Nginx が返す 500 Internal Server Error には、出どころが2つあります。Nginx 自身が処理を続けられずに生成したものと、上流のアプリケーションが返した 500 をそのまま中継しただけのものです。この2つは対処が完全に別なので、最初に切り分ける必要があります。 見分け方は単純です。Nginx 自身が生成した場合、error.log に必ず理由を書いた行が出ます。中継しただけの場合、access.log には 500 が記録されますが、error.log に Nginx 発の行は出ません。つまり、ログを2つ並べて、同じ時刻に対応する行があるかどうかを見れば、責任の所在はその場で決まります。 先に否定しておくべき筋が1つあります。上流への接続が失敗した場合や、上流の応答が遅れて打ち切られた場合は 500 になりません。Nginx のソースでは、接続の失敗は 502 Bad Gateway、時間切れは 504 Gateway Timeout として確定されます。connect() failed (111: Connection refused) の行を見て 500 の原因だと考えるのは、この分岐と食い違います。502 と 504 の調べ方はそれぞれ別記事にあります（Nginx の 502 の記事、504 の記事）。 Nginx 自身が 500 を生成する場面で最も多いのは、内部リダイレクトの循環です。Nginx は1つのリクエストの中で内部的に転送できる回数を10回と定めており、これを使い切ると循環とみなして 500 を返します。この上限は NGX_HTTP_MAX_URI_CHANGES として定義されています。 エラーの概要 利用者側に表示されるのは、次の定型の応答です。この画面だけでは、Nginx 発かアプリケーション発かは判別できません。 <html> <head><title>500 Internal Server Error</title></head> <body> <center><h1>500 Internal Server Error</h1></center> <hr><center>nginx/1.28.0</center> </body> </html> 判別の材料は error.log です。内部リダイレクトの循環なら、次のいずれかの形で記録されます。 ...