トラブルシューティング

よくあるエラーと対処法

Terraformを使用する際によく遭遇するエラーとその対処法を紹介します。エラーメッセージの読み方と、問題を解決するための手順を理解することで、スムーズにトラブルシューティングを行えるようになります。
最終更新: 2026/2/3

よくあるエラーと対処法

Terraformを使用する際によく遭遇するエラーとその対処法を紹介します。エラーメッセージの読み方と、問題を解決するための手順を理解することで、スムーズにトラブルシューティングを行えるようになります。

初期化に関するエラー

Error: Failed to install provider

エラーメッセージ:

Error: Failed to install provider

Error while installing hashicorp/aws v5.0.0: could not query provider
registry for registry.terraform.io/hashicorp/aws

原因:

  • インターネット接続の問題
  • プロキシ設定が必要
  • プロバイダーのバージョンが存在しない

対処法:

# 1. インターネット接続を確認
ping registry.terraform.io

# 2. プロキシ設定(必要な場合)
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# 3. キャッシュをクリアして再試行
rm -rf .terraform
terraform init

Error: Backend initialization required

エラーメッセージ:

Error: Backend initialization required, please run "terraform init"

原因:

  • バックエンド設定を変更した
  • .terraformディレクトリが削除された

対処法:

# 初期化を実行
terraform init

# バックエンドを変更した場合
terraform init -migrate-state

認証に関するエラー

Error: No valid credential sources found

エラーメッセージ:

Error: No valid credential sources found for AWS Provider.

Please see https://registry.terraform.io/providers/hashicorp/aws
for more information about providing credentials.

原因:

  • AWS認証情報が設定されていない
  • 環境変数が正しく設定されていない

対処法:

# 方法1: 環境変数を設定
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_DEFAULT_REGION="ap-northeast-1"

# 方法2: AWS CLIで設定
aws configure

# 方法3: 認証情報ファイルを確認
cat ~/.aws/credentials

# 認証情報が正しく設定されているか確認
aws sts get-caller-identity

Error: Access Denied

エラーメッセージ:

Error: creating EC2 Instance: UnauthorizedOperation: You are not authorized
to perform this operation.

原因:

  • IAMユーザーに必要な権限がない
  • リソースポリシーで拒否されている

対処法:

# 1. 現在のIAMユーザー/ロールを確認
aws sts get-caller-identity

# 2. 必要な権限を確認
# IAMポリシーに以下の権限を追加
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:RunInstances",
        "ec2:DescribeInstances"
      ],
      "Resource": "*"
    }
  ]
}

リソース作成に関するエラー

Error: Resource already exists

エラーメッセージ:

Error: creating S3 Bucket (my-bucket): BucketAlreadyExists: The requested
bucket name is not available.

原因:

  • S3バケット名が既に使用されている(グローバルで一意である必要がある)
  • 他のリソースが既に存在する

対処法:

# 一意な名前を使用
resource "aws_s3_bucket" "example" {
  bucket = "my-unique-bucket-${random_id.bucket_suffix.hex}"
}

resource "random_id" "bucket_suffix" {
  byte_length = 8
}

Error: InvalidParameterValue

エラーメッセージ:

Error: creating EC2 Instance: InvalidParameterValue: Invalid value
'ami-xxxxx' for parameter imageId

原因:

  • AMI IDが指定したリージョンに存在しない
  • AMI IDが無効

対処法:

# データソースを使用して最新のAMIを取得
data "aws_ami" "amazon_linux_2" {
  most_recent = true
  owners      = ["amazon"]
  
  filter {
    name   = "name"
    values = ["amzn2-ami-hvm-*-x86_64-gp2"]
  }
}

resource "aws_instance" "web" {
  ami           = data.aws_ami.amazon_linux_2.id
  instance_type = "t2.micro"
}

Error: Resource limit exceeded

エラーメッセージ:

Error: creating EC2 Instance: InstanceLimitExceeded: You have requested
more instances than your current instance limit allows

原因:

  • AWSのサービスクォータ(制限)に達している

対処法:

# 1. 現在の制限を確認
aws service-quotas get-service-quota \
  --service-code ec2 \
  --quota-code L-1216C47A

# 2. AWSサポートに制限の引き上げをリクエスト
# または、AWS Service Quotasコンソールから申請

状態管理に関するエラー

Error: State lock acquisition failed

エラーメッセージ:

Error: Error acquiring the state lock

Error message: ConditionalCheckFailedException: The conditional request failed
Lock Info:
  ID:        xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx
  Path:      my-terraform-state/prod/terraform.tfstate
  Operation: OperationTypeApply
  Who:       user@hostname
  Version:   1.7.0
  Created:   2024-01-01 12:00:00 UTC

原因:

  • 他のユーザーまたはプロセスが状態ファイルをロックしている
  • 前回の操作が異常終了してロックが残っている

対処法:

# 1. ロック情報を確認
# 他のユーザーが作業中でないことを確認

# 2. ロックを強制解除(慎重に!)
terraform force-unlock <LOCK_ID>

# 3. 再度実行
terraform apply

Error: State file version mismatch

エラーメッセージ:

Error: state snapshot was created by Terraform v1.7.0, which is newer than
current v1.6.0; upgrade to Terraform v1.7.0 or greater to work with this state

原因:

  • 新しいバージョンのTerraformで作成された状態ファイルを、古いバージョンで読み込もうとしている

対処法:

# Terraformをアップグレード
# macOS (Homebrew)
brew upgrade hashicorp/tap/terraform

# Linux (パッケージマネージャー)
sudo apt-get update && sudo apt-get upgrade terraform

# バージョンを確認
terraform version

Error: Failed to read state

エラーメッセージ:

Error: Failed to read state: state data in S3 does not have the expected
content.

原因:

  • 状態ファイルが破損している
  • S3バケットへのアクセス権限がない

対処法:

# 1. S3バケットへのアクセスを確認
aws s3 ls s3://my-terraform-state/

# 2. バックアップから復元
aws s3 cp s3://my-terraform-state/prod/terraform.tfstate.backup \
  s3://my-terraform-state/prod/terraform.tfstate

# 3. ローカルのバックアップから復元
cp terraform.tfstate.backup terraform.tfstate

依存関係に関するエラー

Error: Cycle in resource dependencies

エラーメッセージ:

Error: Cycle: aws_security_group.web, aws_instance.web

原因:

  • リソース間に循環依存が存在する

対処法:

# 悪い例:循環依存
resource "aws_security_group" "web" {
  name = "web-sg"
  
  ingress {
    from_port       = 80
    to_port         = 80
    protocol        = "tcp"
    security_groups = [aws_security_group.app.id]  # appを参照
  }
}

resource "aws_security_group" "app" {
  name = "app-sg"
  
  ingress {
    from_port       = 8080
    to_port         = 8080
    protocol        = "tcp"
    security_groups = [aws_security_group.web.id]  # webを参照(循環)
  }
}

# 良い例:セキュリティグループルールを分離
resource "aws_security_group" "web" {
  name = "web-sg"
}

resource "aws_security_group" "app" {
  name = "app-sg"
}

resource "aws_security_group_rule" "web_to_app" {
  type                     = "ingress"
  from_port                = 8080
  to_port                  = 8080
  protocol                 = "tcp"
  security_group_id        = aws_security_group.app.id
  source_security_group_id = aws_security_group.web.id
}

プラン/適用に関するエラー

Error: Inconsistent dependency lock file

エラーメッセージ:

Error: Inconsistent dependency lock file

The following dependency selections recorded in the lock file are inconsistent
with the current configuration:
  - provider registry.terraform.io/hashicorp/aws

原因:

  • .terraform.lock.hclファイルと実際のプロバイダーバージョンが一致していない

対処法:

# ロックファイルを更新
terraform init -upgrade

# または、ロックファイルを削除して再初期化
rm .terraform.lock.hcl
terraform init

Error: Timeout while waiting for state

エラーメッセージ:

Error: timeout while waiting for state to become 'available'

原因:

  • リソースの作成に時間がかかりすぎている
  • リソースの作成に失敗している

対処法:

# タイムアウト時間を延長
resource "aws_db_instance" "main" {
  identifier     = "mydb"
  engine         = "postgres"
  instance_class = "db.t3.micro"
  
  timeouts {
    create = "60m"
    update = "60m"
    delete = "60m"
  }
}

構文エラー

Error: Argument or block definition required

エラーメッセージ:

Error: Argument or block definition required

An argument or block definition is required here.

原因:

  • HCL構文エラー
  • 閉じ括弧が不足している

対処法:

# フォーマットを実行(構文エラーを検出)
terraform fmt

# 検証を実行
terraform validate

デバッグ方法

ログレベルの設定

# 詳細なログを出力
export TF_LOG=DEBUG
terraform apply

# ログをファイルに保存
export TF_LOG=DEBUG
export TF_LOG_PATH=./terraform.log
terraform apply

# ログレベルの種類
# TRACE - 最も詳細
# DEBUG - デバッグ情報
# INFO  - 一般的な情報
# WARN  - 警告
# ERROR - エラーのみ

プランの詳細確認

# プランをファイルに保存
terraform plan -out=tfplan

# プランの内容を確認
terraform show tfplan

# JSON形式で出力
terraform show -json tfplan | jq

状態の確認

# 状態ファイルの内容を表示
terraform show

# 特定のリソースの状態を表示
terraform state show aws_instance.web

# リソースの一覧を表示
terraform state list

一般的なトラブルシューティング手順

1. エラーメッセージを読む

エラーメッセージには問題の原因が記載されています。

2. ログを確認

export TF_LOG=DEBUG
terraform apply

3. 設定を検証

terraform validate
terraform fmt -check

4. プランを確認

terraform plan

5. 状態を確認

terraform state list
terraform state show <resource>

6. ドキュメントを参照

次のステップ

問題が解決しない場合は、サポートチャネルを活用しましょう。

参考リンク

© 2026 IBM Corporation. Licensed under CC BY 4.0.