terraform plan: Usage, Options & Common CI Errors

Preview exactly what Terraform will change before it touches anything.

terraform plan creates an execution plan: it reads current state, refreshes it, and shows what will be created, updated, or destroyed. In CI you save the plan to a file and feed it to apply.

What it does

terraform plan compares your desired configuration against the current state and real infrastructure, then prints the proposed changes without making them. Saving the plan with -out guarantees apply does exactly what was reviewed.

Common usage

# Preview changes
terraform plan

# Save a plan for a later apply (the CI pattern)
terraform plan -out=tfplan

# Limit to specific resources/variables
terraform plan -target=aws_instance.web -var="env=staging"
terraform plan -var-file=prod.tfvars

# Drift / change gate: exit 2 means "changes present"
terraform plan -detailed-exitcode -input=false

Common error in CI: stale saved plan on apply

A pipeline that plans in one job and applies in another often fails with "Saved plan is stale" or "Error: Saved plan does not match the given configuration". State changed between plan and apply. Fix: run plan and apply against the same locked state in one job, or re-run terraform plan -out=tfplan immediately before terraform apply tfplan. Use a state lock (DynamoDB / native locking) so a parallel run cannot move state underneath you.

Key options

Related guides