Posts

冒頭まとめ 502 Bad Gateway は、要求を取り次いだ中継役が、その先から正常な応答を得られなかったことを示します。同じ 5xx でも、待ちきれずに諦めた場合は 504 です。応答が得られなかったのか、待ち時間が尽きたのかという違いで、疑うべき場所も変わります。 Terraform では、502 の扱いに1つ特徴があります。本体のソースを読むと、レジストリへの問い合わせの再試行回数を設定する処理の説明に、「502 のような再試行可能なエラーに対して行う再試行の回数」と書かれています。つまり Terraform は、502 を再試行で吸収すべきものとして名指しで想定しています。 ところが、その既定値は1回です。合計2回で諦める設計になっており、失敗時の文言に「2回試した」と出るのはこのためです。想定しているにもかかわらず、既定では吸収できる幅が非常に狭い、という状態になっています。この回数は環境変数で増やせます。 もう1つ、読み方の注意点があります。エラー文に現れる URL は、要求の宛先であって、502 を作った相手ではありません。社内のプロキシがその先へ繋げずに 502 を返している場合でも、文言にはレジストリの URL が並びます。「レジストリが落ちている」と判断する前に、応答を作ったのが誰かを確かめてください。 エラーの概要 terraform init の段階では、再試行の回数を含む形になります。 Error: Failed to query available provider packages Could not retrieve the list of available versions for provider example/example: the request failed after 2 attempts, please try again later: 502 Bad Gateway returned from https://registry.terraform.io/v1/providers/... 「2回試した」という数字は、既定の再試行回数が1回であることに対応します。この数字が2以外になっていれば、環境変数で回数が変更されているということです。 プロバイダのファイルを取得する段階でも起きます。この場合、宛先はレジストリではなく配布元です。 Error: Failed to install provider Error while installing example/example v1.2.3: unsuccessful request to https://releases.example.com/terraform-provider-example_1.2.3_linux_amd64.zip: 502 Bad Gateway terraform plan や terraform apply の途中で出る場合は、プロバイダがクラウドの窓口を叩いた結果です。この場合、どの資源の処理で起きたかが示されます。応答の本文が各社のエラー形式ではなく、簡素な HTML であれば、作ったのは窓口ではなく手前の中継役です。 ...

冒頭まとめ Azure で 504 Gateway Timeout を受け取ったとき、出どころは2系統に分かれます。資源の作成や設定変更を受け付ける管理側の窓口が返すものと、利用者からの通信を取り次ぐ中継役が返すものです。前者は Azure Resource Manager、後者は Application Gateway や Azure Front Door などが該当します。 管理側の 504 には、原因を絞り込める特徴があります。文言に、応答しなかったリソースプロバイダの名前が含まれるためです。The gateway did not receive a response from 'Microsoft.Web' within the specified time period. のような形で、Microsoft.Web や Microsoft.App といった名前が入ります。この名前は、どの機能群が応答しなかったかを示します。自分が操作している資源の種類と一致していれば、その資源の担当が遅れています。一致していなければ、内部で呼ばれている別の機能群が遅れています。 最も注意すべき点は2つあります。1つ目は、504 を受け取っても操作が完了している場合があることです。管理側の窓口は要求を受け取って担当へ渡しており、担当の処理は続いています。応答が返る前に取り次ぎ役が待つのをやめただけ、という状況が実際に起きます。 2つ目は、Azure のソフトウェア開発キットの既定の挙動です。共通部分のソースを読むと、再試行の対象となる状態コードは 408・429・500・502・503・504 と定義されています。そのうえで、通常は再送しない POST と PATCH についても、500・503・504 のときだけは再試行する、という例外が明示的に書かれています。つまり、資源を作る要求が 504 で戻った場合、利用者が何もしなくても同じ要求がもう一度送られる可能性があります。 エラーの概要 管理側から返る場合、応答にはコード名と、リソースプロバイダ名を含む文言が入ります。 { "error": { "code": "GatewayTimeout", "message": "The gateway did not receive a response from 'Microsoft.App' within the specified time period." } } 各社の道具を経由している場合も、この文言はそのまま持ち回されます。たとえば構成管理の道具からは、次のような形で表示されます。 ...

冒頭まとめ context deadline exceeded は、Docker が独自に定義したエラーではありません。Docker が書かれている Go 言語の標準の仕組みが返す、時間切れを表すエラーです。Go のソースでは、この文字列を返す値が定義されており、時間切れかどうかを尋ねると真を返すことも明記されています。つまりこの文言が伝えているのは「何かの締め切りに間に合わなかった」という事実だけで、どこの締め切りかは書かれていません。だからこそ、締め切りの持ち主を特定しないまま設定をいじると、直らないまま時間だけが過ぎます。 特定の手がかりは、文言の末尾です。3通りあります。 括弧が何も付かず context deadline exceeded だけの場合、切れたのは呼び出し側が設定した締め切りです。末尾に (Client.Timeout exceeded while awaiting headers) が付く場合、クライアント自身の制限時間が、応答の見出し部分が届く前に切れています。末尾が (Client.Timeout or context cancellation while reading body) の場合、見出しは届いており、本体の転送の途中で切れています。この2つの接尾辞は、Go の HTTP の実装の中でそれぞれ別の場所に定義されており、付く条件も違います。前者なら接続・名前解決・プロキシ・相手の無応答を、後者なら転送速度と転送量を疑う、という具合に、見るべき場所が変わります。 もう1つ、先に否定しておくべき助言があります。「COMPOSE_HTTP_TIMEOUT を大きくする」という案内が今も多く見つかりますが、Docker Compose の公式文書には「Compose V2 では効果がない環境変数」という一覧があり、この環境変数はそこに挙げられています。設定しても何も変わりません。 境界も引いておきます。context canceled は時間切れではなく取り消しで、別のエラーです。Go のソースでも別の値として定義されています。 エラーの概要 実際に見かける形を並べます。まずイメージの取得で出るもの。 Error response from daemon: Get "https://registry-1.docker.io/v2/": context deadline exceeded (Client.Timeout exceeded while awaiting headers) 次にビルドで出るもの。 failed to solve: example:1.0: failed to resolve source metadata: context deadline exceeded そして転送の途中で切れたもの。進捗が途中まで進んでから止まるのが特徴です。 ...

冒頭まとめ invalid reference format は、イメージの指定が文法に合っていない、という判定です。重要なのは、この判定がレジストリへ問い合わせる前に手元で行われることです。通信は一切発生していないので、存在しないイメージを指したときの応答（404）とは別の段階の話になります。認証や通信経路を疑っても意味がありません。 文言は2種類あり、意味がはっきり違います。invalid reference format だけの場合と、invalid reference format: repository name must be lowercase と続く場合です。この2つは、Docker がイメージ名を解析する部分のソースで、明確に別の値として定義されています。解析の流れは、まず文字列を文法と照合し、合わなければ全体を小文字にしてもう一度照合する、という順です。小文字にすれば通る場合だけ「小文字でなければならない」という文言を返し、それ以外はすべて一般の文言になります。 この違いは、原因を絞るのにそのまま使えます。小文字を求める文言が出たということは、Docker が受け取った文字列は「大文字さえ無ければイメージ名として成立していた」ということです。イメージ名を大文字で書いた覚えがないのにこれが出るなら、渡ってしまったのは大文字を含む別の何か、たとえばファイルのパスである可能性が高くなります。 そして、実務で最も多い原因はイメージ名そのものではありません。シェルが Docker に渡した文字列が、書いたつもりのものと違っているという形です。したがって最初にやるべきは、名前を直すことではなく、実際に何が渡ったかを確かめることです。 エラーの概要 実行時の出力はこの形です。 docker: invalid reference format. See 'docker run --help'. 小文字を求める場合はこうなります。 docker: invalid reference format: repository name must be lowercase. See 'docker run --help'. 解析部分のソースには、この判定に関わるエラーが5つ定義されています。文法に合わない場合、小文字でない場合、名前が空の場合、名前が長すぎる場合、タグの書式が不正な場合です。名前の長さの上限は255文字と定義されています。 文法そのものも定義を読むと明快です。名前の各部分は小文字の英数字で始まり、区切りとして点1つ、下線1つか2つ、連続する横棒が使えます。それらを斜線でつないだものが名前です。一方、タグは英数字か下線で始まり、以降に点と横棒を含められ、全体で128文字までです。つまりタグには大文字を使えます。 この非対称は覚えておく価値があります。myapp:V1.0 は通り、MyApp:v1.0 は通りません。名前は小文字だけ、タグは大文字も可、という組み合わせです。 もう1つ、レジストリの指定にも規則があります。名前の先頭部分がレジストリとして扱われるのは、点を含むか、コロンとポート番号が付く場合、そして localhost の場合だけです。定義にもそう書かれています。点もポートも含まない語は、レジストリではなく名前の一部として扱われます。 まず最初に：渡った文字列を確認する 第一に、文言のどちらが出ているかを見ます。小文字を求める文言なら、渡った文字列は大文字を含む何かです。一般の文言なら、小文字にしても通らない文字列です。 第二に、実際に渡った引数を表示させます。シェルの展開を経た後の姿を見るのが目的です。 set -x docker run --rm -v "$(pwd)":/app "$IMAGE:$TAG" set +x 第三に、空の変数を疑います。名前かタグのどちらかが空になると、このエラーになります。次の3つはいずれも同じ結果です。 docker run :latest docker run debian: docker run : 第四に、コマンドを1行に書き直して実行してみます。行の折り返しに使う記号のうしろに余計な空白が入っていると、そこで行が終わったことにならず、想定外の引数が生まれます。この形は目視で見つけにくいので、1行にまとめると再現しなくなることで気付けます。 ...

冒頭まとめ GCP で 504 Gateway Timeout を受け取ったとき、出どころは大きく2つに分かれます。1つは各サービスの窓口（API）が返すもので、内部的には DEADLINE_EXCEEDED という区分に対応します。もう1つは Cloud Load Balancing が返すもので、こちらは背後の処理が時間内に応答しなかった場合に発生します。両者は調べる場所も直し方も違うため、最初に切り分ける必要があります。 窓口が返す 504 については、公式の定義そのものに重要な記述があります。GCP のエラー区分を定めた定義ファイルには、DEADLINE_EXCEEDED の説明として「状態を変更する操作の場合、操作が正常に完了していてもこのエラーが返ることがある」と書かれています。理由も添えられており、成功の応答が遅れて届いた結果、締め切りのほうが先に過ぎた場合がある、とされています。対応する HTTP の状態コードが 504 であることも同じ場所に記載されています。 つまり、作成や更新の操作で 504 を受け取ったとき、それは「失敗した」という通知ではありません。「結果が分からない」という通知です。そのまま再実行すると、二重に作ってしまう恐れがあります。 Cloud Load Balancing が返す 504 については、判別の手がかりがログにあります。statusDetails という項目が response_sent_by_backend であれば、ロードバランサは背後の応答をそのまま渡しただけです。それ以外の値であれば、ロードバランサ自身が作った応答です。公式のトラブルシューティング文書に、この見分け方が明記されています。 なお、種類によって挙動が違う点にも注意が要ります。公式文書によれば、グローバルおよびリージョンの外部アプリケーション ロードバランサは 503 や 504 といった意味のある状態コードを生成しますが、従来型のアプリケーション ロードバランサは常に 502 を使います。従来型を使っている環境では、待ち時間の超過も 502 として現れます。 エラーの概要 窓口が返す場合、応答には区分の名前が含まれます。 { "error": { "code": 504, "message": "Deadline exceeded", "status": "DEADLINE_EXCEEDED" } } 各社の道具やソフトウェアから呼んでいる場合、この区分名がそのままエラー文に現れることが多く、DEADLINE_EXCEEDED の文字列が手がかりになります。 ロードバランサが返す場合、応答は簡素なもので、詳細はログ側にあります。 { "httpRequest": { "status": 504 }, "jsonPayload": { "@type": "type.googleapis.com/google.cloud.loadbalancing.type.LoadBalancerLogEntry", "statusDetails": "backend_timeout" }, "resource": { "type": "http_load_balancer" } } backend_timeout は、公式文書に「背後の応答に時間がかかりすぎた」と説明されており、対処としてバックエンド サービスの待ち時間の設定を見直すか、なぜ応答に時間がかかっているかを調べることが挙げられています。 ...

冒頭まとめ Kubernetes で 504 Gateway Timeout に出会う場面は、大きく2つに分かれます。API サーバーが自分の締め切りに達して要求を打ち切った場合と、Ingress などの中継役が背後の応答を待ちきれずに返した場合です。前者はクラスタの操作そのものが止まり、後者は利用者向けの通信が止まります。原因も対処もまったく別です。 API サーバーが打ち切った場合、文言は一意に定まっています。ソースを読むと、時間切れの応答は Timeout: request did not complete within the allotted timeout という文言で、区分は Timeout、状態コードは 504 として組み立てられます。kubectl からは Error from server (Timeout): の形で表示されます。この文言が出ていれば、打ち切ったのは API サーバー自身です。 締め切りの既定値は60秒です。API サーバーの起動時の指定として定義されており、変更にはクラスタ側の設定変更が要ります。 ここで重要なのが、クライアント側の指定との関係です。要求に待ち時間を付けて送ることはできますが、ソースの処理を読むと、指定された値が0より大きく、かつサーバー側の上限より小さい場合にだけ採用される、と書かれています。つまり、クライアント側で長い値を指定しても、サーバー側の締め切りは伸びません。短くすることはできても、伸ばすことはできない、という一方通行です。「待ち時間を伸ばす」という定番の対処が効かない理由がここにあります。 なお、監視や実行、ログの追従といった長時間動き続ける種類の要求は、この打ち切りの対象から外れます。ソースでも、該当する要求はそのまま通す分岐になっています。 エラーの概要 kubectl からは次の形で見えます。 Error from server (Timeout): error when creating "example.yaml": Timeout: request did not complete within the allotted timeout 応答そのものは次の構造です。区分と状態コードが対応しています。 { "kind": "Status", "status": "Failure", "message": "Timeout: request did not complete within the allotted timeout", "reason": "Timeout", "code": 504 } API サーバー側の記録には、要求ごとの処理時間と結果が残ります。時間切れになった要求は、要した時間とともに記録されます。 "HTTP" verb="GET" URI="/api/v1/namespaces/example/endpoints/sample?timeout=10s" latency="15.79s" resp=504 この例では、要求に10秒の指定が付いているにもかかわらず、15.79秒かかっています。指定した値と実際の処理時間は一致しません。 ...

冒頭まとめ 504 Gateway Timeout は、要求を取り次いだ中継役が、その先からの応答を待ちきれずに返すエラーです。Terraform で目にする場合、出どころは3つに分かれます。本体がレジストリや配布元へ問い合わせたとき、プロバイダがクラウドの窓口へ要求したとき、そして経路上のプロキシや振り分け装置が返したときです。どの段階で出たかによって、調整できる場所も、調整すべき値も変わります。 先に押さえるべき性質が1つあります。504 は「失敗した」という通知ではありません。「待っていた側が待つのをやめた」という通知です。要求を受け取った先が処理を続けている可能性は残ります。作成の操作でこれを受けると、クラウド側には資源が出来上がっているのに Terraform は失敗として扱う、という食い違いが起きます。したがって、504 を受けたあとに最初にやるべきは再実行ではなく、実際に出来ているかどうかの確認です。 再試行の作法も段階ごとに違います。本体がレジストリへ問い合わせる部分は、既定で1回しか再試行しません。合計2回で諦める設計で、失敗時の文言に「2回試した」と出るのはこのためです。この回数は環境変数で増やせます。一方、プロバイダがクラウドの窓口を叩く部分は、各社の実装に従います。たとえば AWS の実装では 500・502・503・504 が再試行の対象と定義され、既定の試行回数は3回です。AWS のプロバイダはこれを25回まで引き上げています。 もう1つ、待ち時間の作法にも癖があります。共通して使われている再試行の仕組みでは、待ち時間は1秒から始めて倍々に増え、上限は30秒です。応答に含まれる待機の指示は 429 と 503 のときだけ読み取られ、504 では読み取られません。 エラーの概要 段階ごとに出方が違います。まず、terraform init の段階でレジストリや配布元から返る場合です。 Error: Failed to install provider Error while installing example/example v1.2.3: unsuccessful request to https://releases.example.com/terraform-provider-example_1.2.3_linux_amd64.zip: 504 Gateway Timeout レジストリへの問い合わせ自体が繰り返し失敗した場合は、再試行の回数を含む形になります。 Error: Failed to query available provider packages Could not retrieve the list of available versions for provider example/example: the request failed after 2 attempts, please try again later: 504 Gateway Timeout returned from https://registry.terraform.io/v1/providers/... この「2回試した」という数字は、既定の再試行回数が1回であることに対応しています。ソースでは、この文言を組み立てる処理が再試行の上限に達したときに呼ばれ、試行回数を添えるようになっています。 ...

冒頭まとめ Terraform の crash は、設定の誤りではなくソフトウェア側の不具合を示します。ただし「Terraform が落ちた」と一口に言っても、中身は2種類あります。Terraform 本体が落ちた場合と、プロバイダのプラグインが落ちた場合です。文言も、確認する場所も、報告する相手も違います。ソースを読むと、この2つには別々の出力文が定義されています。本体が落ちた場合は TERRAFORM CRASH という帯で囲まれた文が出て、報告先は Terraform 本体です。プラグインが落ちた場合は Stack trace from the <プラグイン名> plugin: に続けてスタックトレースが出て、末尾に Error: The <プラグイン名> plugin crashed! が付き、報告先はそのプラグインの保守者です。 実務で頻度が高いのは後者です。そして厄介なのは、プラグインが落ちると、そのプラグインを使っていた他の処理が巻き添えで失敗し、Plugin did not respond や Request cancelled というエラーが大量に並ぶことです。これらは結果であって原因ではありません。原因は、その下に1つだけ出ているスタックトレースです。 もう1つ、先に否定しておくべき手順があります。「crash.log を確認する」という案内が今も広く出回っていますが、このファイルは現在作られません。ソースを比べると、1.0 まではファイルを書き出したうえで、その場所と、機密情報が含まれうるという警告まで表示していました。1.1 以降、その処理も文言も消えています。公式の該当ページにも現在は記述がありません。つまり、スタックトレースは標準エラー出力に流れるだけで、取り逃がすと消えます。最初にやるべきは、出力の保全です。 エラーの概要 出力は3つの形に分かれます。以下は実際に報告された内容をもとにした形です。 プラグインが落ちた場合。巻き添えのエラーが並び、その後にスタックトレースと締めの1文が出ます。 Error: Request cancelled The plugin6.(*GRPCProvider).UpgradeResourceState request was cancelled. Error: Plugin did not respond The plugin encountered an error, and failed to respond to the plugin6.(*GRPCProvider).ReadResource call. The plugin logs may contain more details. Stack trace from the terraform-provider-example_v1.2.3 plugin: panic: runtime error: invalid memory address or nil pointer dereference [signal SIGSEGV: segmentation violation code=0x1 addr=0x0 pc=0xe19f58] ... Error: The terraform-provider-example_v1.2.3 plugin crashed! 本体が落ちた場合。帯で囲まれた文が出て、その後に panic: とスタックトレースが続きます。 ...

冒頭まとめ Terraform の Error acquiring the state lock は、状態ファイルが壊れたという意味ではありません。状態ファイルを同時に書き換えられないよう Terraform が取る鍵を、今回は取れなかったという通知です。原因は突き詰めると2つしかありません。他の実行が本当に鍵を持っているか、鍵を持ったまま終われなかった実行の跡が残っているかです。 判別の材料は、エラー出力に必ず付く Lock Info の7項目です。ID・Path・Operation・Who・バージョン・Created・Info が並び、Terraform のソースでもこの並びの雛形として定義されています。このうち Created（鍵を取った時刻、協定世界時）と Who（利用者名@ホスト名）を読めば、待つべきか外すべきかはほぼ決まります。 先に押さえておきたい性質が1つあります。Terraform は既定では鍵の取得を再試行しません。-lock-timeout の既定値は 0 で、ソースでは指定された時間をそのまま期限として文脈を作るため、0 の場合は最初の1回で失敗が確定します。逆に -lock-timeout=5m のように指定すると、1秒から始めて倍々に伸ばし、最大16秒間隔で、指定時間まで再試行を続けます。「待てば通ったはずのエラー」を即座の失敗として受け取っていることが、実際には少なくありません。 境界も引いておきます。-lock=false は解決ではなく回避です。Terraform 自身のエラー本文にも、ほとんどのコマンドで無効化できるが推奨しないと書かれています。また Error releasing the state lock は逆向きのエラーで、鍵を外す側の失敗です。 エラーの概要 実際の出力は次の形です。冒頭の見出しと、定型の説明文、そして Lock Info が続きます。 Error: Error acquiring the state lock Error message: operation error S3: PutObject, https response error StatusCode: 412, api error PreconditionFailed: At least one of the pre-conditions you specified did not hold Lock Info: ID: 3f6a1c9e-1f2b-4a55-9d1c-0a7e2b9c4d51 Path: my-tfstate-bucket/prod/terraform.tfstate.tflock Operation: OperationTypeApply Who: deploy@runner-07 Version: 1.11.4 Created: 2026-07-28 02:14:22.5 +0000 UTC Info: Lock Info の7項目は、Terraform のソースに文字列の雛形として定義されています。ID は鍵の識別子で、後述の解除コマンドに渡す値です。Path は鍵の置き場所で、どのバックエンドのどの状態ファイルかが分かります。Operation は実行しようとした操作（OperationTypeApply など）、Who は利用者名とホスト名を @ でつないだもの、バージョンは鍵を取った側の Terraform のバージョン、Created は鍵を取った時刻で協定世界時、Info は呼び出し側が付ける補足で、空のことが多い項目です。 ...

冒頭まとめ GitHub API の 405 Method Not Allowed は、名前から受ける印象と中身が食い違うコードです。HTTP のメソッドを間違えたという意味ではありません。GitHub 公式の API 定義（OpenAPI）で数えると、405 を応答として定義している操作は全1,209操作のうち3つしかなく、そのうち実務で当たるのは事実上1つ、プルリクエストのマージ（PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge）です。この 405 に付けられた定義文は「マージを実行できない場合」であり、意味は「メソッドが違う」ではなく「今はマージできない」です。 応答本文には、422 のような errors 配列がありません。公式定義でも message と documentation_url の2つだけです。つまり調査は、message の文言を読むことに尽きます。実際に記録されている文言は5系統に整理できます。マージできる状態にない（Pull Request is not mergeable）、base ブランチが動いた（Base branch was modified. Review and try the merge again.）、必須ステータスチェックが未完了、必要なレビューが足りない、そのブランチへ push する権限がない、の5つです。 リトライしてよいかどうかも系統で分かれます。Base branch was modified だけが一時的な状態で、待って再試行するのが正しい対処です。残りは、状態を直さない限り何度送っても同じ結果になります。 境界を先に1つ引いておきます。マージ要求に sha を渡して head が一致しなかった場合は、405 ではなく 409（Head branch was modified. Review and try the merge again.）です。Base と Head の違いしかない文言で、ステータスコードも対処も異なります。 エラーの概要 公式 API 定義におけるマージ操作の 405 は、message と documentation_url を持つだけの単純なスキーマで、例として示されている値は Pull Request is not mergeable です。実際の応答は次の形になります（マージを自動化するボットが記録に残したもので、status はクライアント側が付けた項目です）。 ...