Opscraft
Terraform · Lesson 11 of 12 · 3 min read

Troubleshooting Terraform

Enlarge diagramStopdo not applyFind the causethe plan line marked "forcesreplacement"Was it a rename?add a moved blockWas it an attribute?revert it, or ignore_changes ifmanaged elsewherePlan againuntil the replacement is goneProtect itprevent_destroy,deletion_protection123456
Figure 1. When a plan unexpectedly wants to replace something important, stop and work through it in this order.
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.