Terraform · Lesson 11 of 12 · 3 min read
Troubleshooting Terraform
Enlarge diagram
Swipe sideways to see all of it, or tap to open it full screen.
| Error / symptom | Cause | Fix |
|---|---|---|
Error acquiring the state lock |
Another run in progress, or a crashed run | Wait; if stale, force-unlock after verifying |
resource already exists / EntityAlreadyExists |
Real resource exists but isn't in state | import it, or rename |
Plan shows -/+ (replace) on a database |
A ForceNew attribute changed (engine, AZ, identifier, subnet group...) or an address change | Stop; find the forcing attribute (plan says # forces replacement), revert or use moved/ignore_changes, plan a migration |
Invalid count argument / Invalid for_each argument |
Count/keys depend on values unknown until apply | Use static keys; split into two applies; -target as a last resort |
Cycle: error |
Circular references | Break the loop (e.g. separate security group rules from groups) |
| Perpetual diff on every plan | Provider normalises a value differently (JSON policy ordering, timestamps), or something outside changes it | jsonencode/aws_iam_policy_document, ignore_changes, fix the external process |
Provider produced inconsistent result |
Provider bug or eventual consistency | Retry; upgrade provider; report |
| Timeouts creating resources | Slow AWS operations (EKS, RDS) | timeouts {} block, check events in the AWS console |
| Plans differ between laptop and CI | Different provider/Terraform versions, credentials, variables | Commit the lock file, pin required_version, run plans only in CI |
| Slow plans | Huge state, many data sources | Split stacks, reduce refresh scope (-refresh=false cautiously) |
Debug logging: TF_LOG=DEBUG terraform plan 2> debug.log (or TRACE), TF_LOG_PROVIDER for provider-only logs.