# 1. Enable debug logging
export TF_LOG=DEBUG
export TF_LOG_PATH=/tmp/terraform.log

# 2. Validate syntax
terraform validate

# 3. Run plan with detailed output
terraform plan -out=tfplan

# 4. Review logs for errors
cat /tmp/terraform.log | grep -i error

# 5. Disable logging when done
unset TF_LOG
unset TF_LOG_PATH

# Set debug logging
export TF_LOG=DEBUG
export TF_LOG_PATH=/tmp/terraform.log

# Available levels: TRACE, DEBUG, INFO, WARN, ERROR
# TRACE: Most verbose, includes all operations
# DEBUG: Detailed, good for troubleshooting
# INFO: General information

# Filter for errors
cat /tmp/terraform.log | grep -i error

# Filter for specific resource
cat /tmp/terraform.log | grep "google_pubsub"

# Filter for timestamps
cat /tmp/terraform.log | grep "2025-11-14"

# 1. Validate HCL syntax
terraform validate
# ✓ Catches syntax, type, and required argument errors
# ✗ Does NOT validate against actual cloud state

# 2. Format code (catches formatting issues)
terraform fmt -check -recursive
terraform fmt -recursive  # Fix formatting

# 3. Refresh state (sync with actual infrastructure)
terraform refresh
# ✓ Updates Terraform state to match real infrastructure
# ✗ Does NOT make changes, only reads

# 4. Re-initialize (if provider issues)
terraform init -upgrade
# ✓ Updates provider versions to latest compatible
# ✗ Requires time for downloads

# 5. Plan with detailed output
terraform plan -out=tfplan
# ✓ Shows exactly what will change
# ✗ Does NOT make changes

# 6. Check logs
grep -i error /tmp/terraform.log

# Option 1: Wait for lock (if operation is legitimately running)
terraform apply -lock-timeout=10m

# Option 2: Force unlock (use with caution!)
terraform force-unlock LOCK_ID
# Get LOCK_ID from error message

# Option 3: Manual recovery (last resort)
# Delete lock file from GCS backend
gsutil rm gs://bucket/prefix/default.tflock

Error: Cycle: resource_a, resource_b, resource_a

# ❌ BAD: Circular reference
resource "google_compute_firewall" "allow_app" {
  source_tags = [google_compute_instance.app.tags[0]]
}
resource "google_compute_instance" "app" {
  tags = [google_compute_firewall.allow_app.name]
}

# ✅ GOOD: Break dependency
resource "google_compute_firewall" "allow_app" {
  source_tags = ["app"]  # Use explicit string instead
}
resource "google_compute_instance" "app" {
  tags = ["app"]  # Explicit value
}

Error: Incompatible provider version

Terraform requires >= 5.26.0, < 5.27.0
You have 6.0.0 installed

# 1. Check current version
terraform version

# 2. Lock to compatible version
# In main.tf
terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 5.26.0"  # Allows 5.26.x, not 5.27.0
    }
  }
}

# 3. Re-initialize
terraform init -upgrade

# 4. Commit .terraform.lock.hcl
git add .terraform.lock.hcl
git commit -m "lock: pin Google provider to 5.26.0"

Error: Error creating PubSub topic: googleapi: Error 403:
The caller does not have permission

# 1. Check current authentication
gcloud auth list
gcloud config get-value project

# 2. Verify service account permissions
gcloud projects get-iam-policy ecp-wtr-supplier-charges-prod \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:app-runtime@*"

# 3. Grant required role
gcloud projects add-iam-policy-binding ecp-wtr-supplier-charges-prod \
  --member="serviceAccount:app-runtime@project.iam.gserviceaccount.com" \
  --role="roles/pubsub.editor"

# 4. Re-plan
terraform plan

# Detect drift
terraform plan
# Shows changes that don't exist in your .tf files

# Sync state
terraform refresh
# Updates state to match real infrastructure

# Manual fix (if refresh fails)
terraform import google_pubsub_topic.incoming \
  projects/ecp-wtr-supplier-charges-prod/topics/my-topic

# Remove from state (if resource manually deleted)
terraform state rm google_pubsub_topic.incoming

# View recent state changes
terraform state list
terraform state show google_pubsub_topic.incoming

# See what changed in last apply
terraform show tfplan | head -50

# Rollback by re-applying previous configuration
git checkout HEAD~1  # Go back one commit
terraform plan
terraform apply

# Error occurs
# Error: Error acquiring the state lock
# Lock Info:
#   ID:        abc123def456
#   Path:      gs://terraform-state-prod/supplier-charges-hub/default.tflock
#   Created:   2025-11-14 10:30:00 UTC

# Step 1: Check if operation is running
gcloud compute operations list --filter="status:RUNNING"

# Step 2: If no running operation, force unlock
terraform force-unlock abc123def456

# Step 3: If force-unlock fails, delete lock file
gsutil rm gs://terraform-state-prod/supplier-charges-hub/default.tflock

# Step 4: Re-plan to verify state is correct
terraform refresh
terraform plan

# Error occurs
# Error: Invalid value for module argument

# Step 1: Validate syntax
terraform validate

# Output shows exactly what's wrong:
# Error: Missing required argument
#   on pubsub.tf line 5, in resource "google_pubsub_topic" "topics":
#    5: resource "google_pubsub_topic" "topics" {
# The argument "name" is required, but was not set.

# Step 2: Review and fix the file
# Add missing argument:
resource "google_pubsub_topic" "topics" {
  name = "my-topic"  # Add this
}

# Step 3: Validate again
terraform validate

# Error occurs
# Error creating PubSub topic: googleapi: Error 403

# Step 1: Check authentication
gcloud auth list
gcloud config get-value project

# Step 2: Get current IAM bindings
gcloud projects get-iam-policy ecp-wtr-supplier-charges-prod

# Step 3: Add Pub/Sub Editor role
gcloud projects add-iam-policy-binding ecp-wtr-supplier-charges-prod \
  --member="serviceAccount:terraform@project.iam.gserviceaccount.com" \
  --role="roles/pubsub.editor"

# Step 4: Re-run Terraform
terraform plan
terraform apply