WARNINGTerraformInfrastructure as Code

Terraform apply blocked by stale state lock

terraformstatelockdynamodbs3

Symptoms

terraform apply errors with 'Error acquiring the state lock'
LockID is present in DynamoDB after a failed CI job
Nobody else is currently running Terraform

Root Cause

CI runner crashed or was cancelled mid-apply and never released the lock
Network partition between runner and the DynamoDB backend
Manual `terraform apply` run with Ctrl+C

Diagnosis

Check who owns the lock in the error message (Who/When fields)
Inspect the DynamoDB lock table for the LockID entry
Verify no other pipeline is still executing

Fix

Force-unlock after confirming no live apply:

terraform force-unlock -force <LOCK_ID>

If state is corrupted, restore from the most recent S3 version:

aws s3api list-object-versions --bucket tf-state --prefix prod/terraform.tfstate
aws s3api copy-object --copy-source tf-state/prod/terraform.tfstate?versionId=<id> \
  --bucket tf-state --key prod/terraform.tfstate

Prevention

Run Terraform with `-lock-timeout=10m` to wait instead of failing fast
Use short-lived credentials scoped per pipeline run
Alert on state locks held longer than 15 minutes