Terraform

冒頭まとめ 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 は呼び出し側が付ける補足で、空のことが多い項目です。 ...

エラーの概要 Terraform の 409 エラーは、Terraform が作成・更新しようとするリソースが既にクラウド環境に存在し、状態ファイル（tfstate）に記録された期待値と実際のリソース状態に競合が生じていることを示します。このエラーは特にマルチユーザー環境や手動でリソースを作成した後に Terraform で管理を開始する場合に発生しやすくなります。 実際のエラーメッセージ例 Error: Error creating XXX: XXX (xxx): InvalidParameterException: Resource already exists on main.tf line 42, in resource "aws_instance" "web": 42: resource "aws_instance" "web" { Error: ConflictException { "error": "conflict", "message": "The resource with name 'my-bucket' already exists", "status_code": 409 } よくある原因と解決手順 原因 1：手動で作成したリソースを Terraform で管理しようとしている クラウド管理コンソールやコマンドラインで直接作成したリソースに対して、Terraform コードで同じリソースを定義すると、Terraform はそのリソースが「新規作成される対象」だと判断します。しかし実際にはリソースが存在するため、作成時に 409 エラーで競合が検出されます。 この場合、terraform import コマンドを使い、既存のリソースを Terraform の管理下に移す必要があります。 Before（エラーが起きるコード）： resource "aws_s3_bucket" "data_bucket" { bucket = "my-existing-bucket" } AWS マネジメントコンソールで my-existing-bucket が既に存在している場合、terraform apply 実行時に 409 エラーが発生します。 ...

エラーの概要 HTTP 429 エラーは「Too Many Requests」を意味し、Terraform の実行時にクラウドプロバイダーの API レート制限に達したことを示します。AWS・Google Cloud・Azure など複数のプロバイダーが API 呼び出しの頻度を制限しており、Terraform がこの上限を超えたときに発生します。特に大規模なインフラストラクチャをコード化する際に、並列処理による過度な API 呼び出しが原因となることが多くあります。 実際のエラーメッセージ例 Terraform 実行時に以下のようなエラーが出力されます。 { "error": "error creating Security Group: RequestLimitExceeded: Request limit exceeded", "status_code": 429 } また、Terraform の標準出力では以下のように表示されることもあります。 Error: Error creating load balancer: InvalidParameterValue on main.tf line 42, in resource "aws_lb" "example": 42: resource "aws_lb" "example" { 429 Too Many Requests よくある原因と解決手順 原因 1：Terraform の並列実行数が多すぎる Terraform はデフォルトで 10 個のリソースを同時に作成する設定になっており、これが API レート制限に抵触します。特に AWS や Google Cloud のプロバイダーでは、単位時間あたりの API 呼び出し数に制限があり、デフォルトの並列度では超過しやすくなります。 修正前： terraform apply -auto-approve # デフォルトの並列度 10 で実行 修正後： ...

エラーの概要 Terraform の 401 エラーは、クラウドプロバイダー（AWS・Azure・GCP等）または Terraform Cloud/Enterprise への認証に失敗したときに発生します。認証情報の不足・期限切れ・形式エラーなどが原因で、リソースの操作やプランの実行が中断されます。 実際のエラーメッセージ例 Error: error configuring Terraform AWS Provider: error validating provider credentials: error calling sts:GetCallerIdentity: InvalidClientTokenId: The security token included in the request is invalid on main.tf line 1, in provider "aws": 1: provider "aws" { Error: Failed to retrieve available provider versions from Terraform Registry (registry.terraform.io). This may be caused by network connectivity issues, or an incorrect API token. HTTP status code: 401 Unauthorized よくある原因と解決手順 原因1：AWS アクセスキーの認証情報が不正または期限切れ AWS のアクセスキーが間違っているか、IAM（AWS Identity and Access Management）ユーザーの権限が削除されている場合に発生します。特に複数の AWS アカウントを扱う環境では、設定ミスが起こりやすくなります。 Before（エラーが起きるコード）： # 期限切れまたは不正なキーを使用 export AWS_ACCESS_KEY_ID=<your-access-key-id> export AWS_SECRET_ACCESS_KEY=<your-secret-access-key> terraform plan After（修正後）： # 最新の認証情報を取得・確認 aws sts get-caller-identity # 有効なキーを再設定 export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7NEWKEY export AWS_SECRET_ACCESS_KEY=<your-secret-access-key> # または ~/.aws/credentials ファイルで管理 cat ~/.aws/credentials terraform plan 原因2：環境変数が設定されていない Terraform が認証情報を探すとき、環境変数（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY など）が未設定の場合、プロバイダー認証に失敗します。特に CI/CD パイプラインやサーバーレス環境では見落としやすい原因です。 ...

エラーの概要 Terraform が AWS などのクラウドプロバイダーにリソースの作成・更新・削除を要求したとき、IAM ポリシーまたは SCP（Service Control Policy）により操作が拒否される状態です。このエラーは実行ロールに必要な権限がないか、組織レベルの制限によって操作が許可されていないことを示しています。 実際のエラーメッセージ例 { "Error": { "Code": "AccessDenied", "Message": "User: arn:aws:iam::123456789012:user/terraform-user is not authorized to perform: ec2:RunInstances on resource: arn:aws:ec2:us-east-1:123456789012:instance/* with an implicit deny in user-based policy" } } Error: error creating EC2 Instance: UnauthorizedOperation.Unavailable: You are not authorized to perform this operation. status code: 403, request id: <request-id> on main.tf line 10, in resource "aws_instance" "example": 10: resource "aws_instance" "example" { よくある原因と解決手順 原因1：実行ロールに IAM ポリシーの権限が不足している Terraform を実行するユーザーまたはロールに、リソース作成に必要な IAM 権限がアタッチされていません。例えば EC2 インスタンスを起動する場合、ec2:RunInstances アクションの許可が必要です。IAM ポリシーシミュレーター（ポリシーが実際に機能するかを事前検証するツール）で実際に権限が付与されているかを確認し、不足している権限をポリシーに追加します。 ...

エラーの概要 Terraform の 404 エラーは、設定ファイルで参照しているクラウドリソースが実際には存在しないか、削除されている状態を示します。このエラーが発生すると、terraform plan や terraform apply の実行が中断され、リソース間の依存関係が解決できません。特に data source を使ってリソース情報を取得する場合や、既存リソースを参照する設定で頻出します。 実際のエラーメッセージ例 AWS Provider での例： Error: error reading EC2 Instance: InvalidInstanceID.NotFound on main.tf line 12, in data "aws_instance" "existing": 12: data "aws_instance" "existing" { │ │ InvalidInstanceID.NotFound: The instance ID 'i-0123456789abcdef0' does not exist Google Cloud Provider での例： Error: Error when reading or editing Compute Instance: googleapi: Error 404: The resource 'projects/my-project/zones/us-central1-a/instances/old-instance' was not found よくある原因と解決手順 原因 1：data source で参照しているリソースがまだ作成されていないか削除されている リソースを作成する前に、そのリソース情報を data source で参照しようとするケースがよくあります。また、クラウドコンソールから手動でリソースを削除した場合、Terraform の state ファイルにはまだ存在するとして記録されたままになり、再度参照しようとすると 404 エラーになります。 Before（エラーが起きるコード）： # EC2 インスタンスを作成する前に参照しようとしている data "aws_instance" "existing" { instance_ids = ["i-0123456789abcdef0"] } resource "aws_instance" "new" { ami = data.aws_instance.existing.ami instance_type = "t3.micro" } After（修正後）： ...

エラーの概要 Terraform で 400 エラーが発生する場合、これはクラウドプロバイダーの API が「不正なリクエスト」と判定したことを意味します。HCL の構文自体は正しくても、リソース定義のパラメーター型や値がプロバイダーの期待形式と一致していない場合に起こります。terraform apply 実行時に最も頻繁に遭遇するエラーで、本来なら terraform plan で事前に検出すべき問題です。 実際のエラーメッセージ例 Error: error creating DB Instance: BadRequest: 400 Bad Request on main.tf line 15, in resource "aws_db_instance" "example": 15: resource "aws_db_instance" "example" { with aws_db_instance.example, on main.tf line 15, in resource "aws_db_instance" "example": 15: resource "aws_db_instance" "example" { Error: Error making API call: status code 400, message: invalid parameter value $ terraform apply Error: error creating resource: BadRequest: The request body is malformed │ │ with module.vpc.aws_security_group.allow_ssh: │ on vpc/main.tf line 42, in resource "aws_security_group" "allow_ssh": │ 42: resource "aws_security_group" "allow_ssh" { よくある原因と解決手順 原因 1：リソースパラメーターの型が不正 Terraform のプロバイダーが期待する型（文字列、数値、リスト等）と異なる型で値を指定すると、API リクエスト生成時に 400 エラーが発生します。特に、数値として指定すべきポート番号を文字列で渡したり、ブール値を文字列で指定したりするケースが多く見られます。 Before（エラーが起きるコード）： resource "aws_security_group" "example" { name = "example-sg" description = "Example security group" ingress { from_port = "80" # 型エラー：文字列ではなく数値であるべき to_port = "443" # 型エラー protocol = "tcp" cidr_blocks = ["0.0.0.0/0"] } depends_on = true # 型エラー：ブール値ではなく string の list } After（修正後）： ...

冒頭まとめ Terraform の実行中に現れる 500 Internal Server Error は、手元で動いている Terraform 自身の不具合ではなく、Terraform が通信している相手側のサーバー内部エラーです。Terraform は多数のリモート API のクライアントであり、相手は大きく3つに分かれます。plan や apply の最中にリソースを操作するクラウドプロバイダーの API（原因1）、state の保存や取得、リモート実行を担うバックエンド（HCP Terraform など。原因2）、そして terraform init でプロバイダーやモジュールを取得する Terraform Registry（原因3）です。500の調査の第一歩は、エラーメッセージに含まれる URL と、どの段階で失敗したかを読んで、この3つのどれが相手かを特定することです。 境界も先に押さえておくと迷いません。実行アカウントの権限不足は、クラウド側から 403 系のアクセス拒否（AWS なら AccessDenied や UnauthorizedOperation）として返り、500にはなりません。AWS のスロットリングは ThrottlingException（HTTP では 400 として現れることもあります）や 429 で、プロバイダーが自動で再試行する対象です。また、TERRAFORM CRASH という見出しとスタックトレースが出る異常終了は、HTTP の500ではなく Terraform 本体のバグであり、調査の場所がまったく異なります。 エラーの概要 Terraform の500は、相手ごとに異なる文言で現れます。いずれもメッセージの中に相手を特定する手がかりが含まれています。 クラウドプロバイダーの API が相手の場合、リソース操作のエラーとして表示され、リクエスト先のエンドポイントが含まれます。 Error: creating EC2 Instance: 500 Internal Server Error on main.tf line 12, in resource "aws_instance" "example": バックエンドが相手の場合の実例は、HashiCorp の公式文書（Terraform Enterprise の障害復旧ガイド）にそのまま掲載されています。リモートバックエンドから state を取得できなかったケースです。 ...