Troubleshooting

Error: Cycle detected in component dependencies

# Before (circular dependency)
component "vpc" {
  source = "./modules/vpc"
  inputs = {
    security_group_id = component.app.security_group_id  # References app
  }
}

component "app" {
  source = "./modules/app"
  inputs = {
    vpc_id = component.vpc.vpc_id  # References vpc
  }
}

# After (broken circular reference)
component "vpc" {
  source = "./modules/vpc"
  inputs = {
    # Remove reference to app
  }
}

component "security_group" {
  source = "./modules/security-group"
  inputs = {
    vpc_id = component.vpc.vpc_id
  }
}

component "app" {
  source = "./modules/app"
  inputs = {
    vpc_id             = component.vpc.vpc_id
    security_group_id  = component.security_group.id
  }
}

Error: Unsupported argument
  on variables.tfcomponent.hcl line 5:
  5:   validation {

Validation blocks are not supported in Stack configurations

# Incorrect
variable "instance_count" {
  type = number
  validation {
    condition     = var.instance_count > 0
    error_message = "Instance count must be positive"
  }
}

# Correct
variable "instance_count" {
  type        = number
  description = "Number of instances (must be positive)"
}

Error: Missing required argument
  on variables.tfcomponent.hcl line 3:
  3: variable "region" {

The argument "type" is required in Stack variable declarations

# Incorrect
variable "region" {
  default = "us-west-1"
}

# Correct
variable "region" {
  type    = string
  default = "us-west-1"
}

Error: Provider configuration not allowed in module

Modules used with Terraform Stacks cannot contain provider blocks

deployment "old_environment" {
  inputs = {
    aws_region     = "us-west-1"
    instance_count = 2
    role_arn       = local.role_arn
    identity_token = identity_token.aws.jwt
  }

  destroy = true  # Marks deployment for destruction
}

# Get deployment step diagnostics
terraform stacks deployment-run list
# Note the run ID, then:
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://app.terraform.io/api/v2/stack-deployment-runs/{run-id}/stack-deployment-steps" | \
  jq '.data[] | {id, status: .attributes.status, component: .attributes["component-name"]}'

# Approve all pending plans in a deployment run
terraform stacks deployment-run approve-all-plans -deployment-run-id=sdr-ABC123

# Or approve all plans in a deployment group
terraform stacks deployment-group approve-all-plans -deployment-group=canary

deployment_auto_approve "safe_changes" {
  deployment_group = deployment_group.canary

  check {
    condition = context.plan.applyable
    reason    = "Plan must be successful"
  }
}

Error: Error assuming role with web identity
Error: Failed to retrieve credentials
Error: Invalid identity token

# Check identity_token block exists
identity_token "aws" {
  audience = ["aws.workload.identity"]
}

# Check deployment references the token
deployment "production" {
  inputs = {
    identity_token = identity_token.aws.jwt
  }
}

provider "aws" "this" {
  config {
    region = var.aws_region
    assume_role_with_web_identity {
      role_arn           = var.role_arn
      web_identity_token = var.identity_token
    }
  }
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<account-id>:oidc-provider/app.terraform.io"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "app.terraform.io:aud": "aws.workload.identity"
        },
        "StringLike": {
          "app.terraform.io:sub": "organization:<org-name>:project:<project-name>:stack:<stack-name>:deployment:<deployment-name>"
        }
      }
    }
  ]
}

Error: Failed to install provider
Error: Provider version not found
Error: Checksum mismatch for provider

terraform stacks providers-lock

terraform stacks providers-lock \
  -platform=linux_amd64 \
  -platform=darwin_amd64 \
  -platform=darwin_arm64

required_providers {
  aws = {
    source  = "hashicorp/aws"
    version = "~> 5.7.0"  # Ensure version constraint is valid
  }
}

Error: Unsupported attribute
Error: Invalid reference
Error: Missing required argument

component "alb" {
  source  = "terraform-aws-modules/alb/aws"
  version = "8.7.0"  # Use specific version known to work
  # ...
}

# Instead of using a module that has issues
component "alb" {
  source = "./modules/alb"  # Create local module with raw resources
  # ...
}

Error: Module not found
  Could not load module ./modules/vpc

# Correct
component "vpc" {
  source = "./modules/vpc"
}

# Incorrect (absolute paths don't work)
component "vpc" {
  source = "/Users/username/project/modules/vpc"
}

my-stack/
├── components.tfcomponent.hcl
└── modules/
    └── vpc/
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

Error: Reference to unknown component
  Component "vpc" has not been defined

component "vpc" {
  source = "./modules/vpc"
  # Must define component before referencing it
}

component "app" {
  source = "./modules/app"
  inputs = {
    vpc_id = component.vpc.vpc_id  # Now valid
  }
}

# In modules/vpc/outputs.tf
output "vpc_id" {
  value = aws_vpc.main.id
}

component "regional" {
  for_each = var.regions
  # ...
}

component "app" {
  inputs = {
    # Correct - reference specific instance
    vpc_id = component.regional["us-west-1"].vpc_id

    # Incorrect - can't reference for_each component directly
    # vpc_id = component.regional.vpc_id
  }
}

Error: Maximum deferred change iterations reached

curl "https://app.terraform.io/api/v2/stack-deployment-steps/{step-id}/stack-diagnostics"

{
  "data": []
}

curl "https://app.terraform.io/api/v2/stack-deployment-steps/{step-id}/stack-diagnostics?stack_deployment_step_id={step-id}"

# Get final apply step ID first
APPLY_STEP=$(terraform stacks deployment-run list --json | \
  jq -r '.[0].deployment_steps[] | select(.operation_type == "apply") | .id' | tail -1)

# Get outputs
curl -L -s -H "Authorization: Bearer $TOKEN" \
  "https://app.terraform.io/api/v2/stack-deployment-steps/$APPLY_STEP/artifacts?name=apply-description" | \
  jq -r '.outputs | to_entries | .[] | "\(.key): \(.value.change.after)"'

# Check step status first
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://app.terraform.io/api/v2/stack-deployment-steps/{step-id}" | \
  jq '.data.attributes.status'

# Only request artifacts when status is "completed"
if [ "$STATUS" = "completed" ]; then
  curl -L -H "Authorization: Bearer $TOKEN" \
    "https://app.terraform.io/api/v2/stack-deployment-steps/{step-id}/artifacts?name=apply-description"
fi

# curl: Use -L flag
curl -L -H "Authorization: Bearer $TOKEN" \
  "https://app.terraform.io/api/v2/stack-deployment-steps/{step-id}/artifacts?name=apply-description"

# Python requests: allow_redirects=True (default)
import requests
response = requests.get(url, headers=headers, allow_redirects=True)

# Node.js fetch: redirect: 'follow' (default)
const response = await fetch(url, {
  headers: headers,
  redirect: 'follow'
});

# CLI commands
TF_LOG=DEBUG terraform stacks validate
TF_LOG=DEBUG terraform stacks configuration upload

# API artifacts
# Request the debug-log artifact instead of description
curl -L -H "Authorization: Bearer $TOKEN" \
  "https://app.terraform.io/api/v2/stack-deployment-steps/{step-id}/artifacts?name=apply-debug-log"

terraform stacks configuration list