mediumAdvancedUSE#plan#refresh#timeout#performance

Plan too slow — refresh hitting every resource

terraform plan takes > 10 minutes for a small change

Likely source:performancescaling

Focused incident mode — strips away everything but this runbook.

Symptoms

  • terraform plan takes > 10 minutes for a small change
  • Plan times out in CI with no output
  • Refresh phase stalls on specific resources

For very large state files, consider splitting into workspaces or using -target for daily iteration and running full plans less frequently.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Plan timing

    time terraform plan 2>&1 | tail -5

  • Refresh-only plan time

    time terraform plan -refresh-only 2>&1 | tail -5

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • terraform state list shows hundreds of resources
  • Plan takes > 10 minutes without -target

Confirm before fixing

terraform state list | wc -l
READ

Count managed resources

Fix

terraform plan -target=<RESOURCE-ADDR>
CHANGE

Use -target to limit scope for fast iteration

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
terraform state list | wc -l
READ

Count managed resources to understand the scope

2
terraform plan -target=<RESOURCE-ADDR>
CHANGE

Narrow the plan to only the changed resource

3
terraform plan -parallelism=5
CHANGE

Reduce parallelism to avoid API throttling

4
time terraform plan 2>&1 | tail -5
READ

Measure improvement

Prevention

  • Split large Terraform root modules into smaller workspaces.
  • Use -target in CI for PR checks; run full plan on merge.
  • Monitor provider API quotas and request increases if needed.
  • Clean up stale state entries regularly with terraform state rm.

Related runbooks

Same stack, same failure family — worth a skim.

Corrupted local state — JSON parse error in state filecritical

Error: Error loading state: SyntaxError: JSON input

TerraformAdvanced2 causes
Open runbook
Backend initialization required — run terraform initmedium

Backend initialization required: please run "terraform init"

TerraformFoundation2 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.