Immutable solution version
Diagnosing a Terraform plan that takes forever
Complete solution
Plans that hang or crawl have three usual causes: too many resources refreshing, a slow provider API, or dependency chains serializing everything. The procedure isolates which one.
Diagnosing a Terraform plan that takes forever
Symptom
terraform plan runs for tens of minutes or appears hung. CI timeouts kill it.
Cause
- Refresh fan-out: hundreds of resources each needing an API read, some paginated or throttled.
- Provider API slowness: one data source or resource with an expensive query (list-all calls, cross-region reads).
- Serialization: long
depends_onchains or module dependencies forcing sequential operations that could be parallel.
Confirmation
- Run with
TF_LOG=INFOand watch which provider calls take the longest. The log timestamps per API call; the slow ones stand out. terraform plan -refresh=false: if this is fast, the cost is in refresh (cause 1 or 2). If still slow, the cost is in planning logic or serialization (cause 3).- Count resources:
terraform state list | wc -l. Hundreds of resources with per-object API reads is inherently slow; that is a design fact, not a bug.
Fix
- Refresh cost: split the config into smaller workspaces so each plan refreshes less. There is no flag that makes 2000 API reads fast.
- Slow data source: narrow it (specific IDs instead of list-all with filters), or replace a data source with a variable when the value is stable.
- Serialization: remove unnecessary
depends_on(references already imply ordering). Break long module chains with data sources where the dependency is read-only. -parallelismexists but raising it against a throttling API makes things worse. Fix the call pattern first.
Verification
- Time the plan before and after. "Faster" needs a number.
terraform plan -refresh=falsevs full plan timings tell you whether refresh is still the dominant cost.- The plan output must be identical in content, just faster. Speedups that change the plan are not speedups.
Evidence
Plan refreshes state via provider APIs; -refresh=false skips refresh; -parallelism controls concurrent operations. Verified against live docs 2026-09-26.
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_NpUxHwQtPQrFNbEJBL9bfA" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Diagnosing a Terraform plan that takes forever <span>— Vectle</span></a>