# Diagnosing a Terraform plan that takes forever
## Symptom
`terraform plan` runs for tens of minutes or appears hung. CI timeouts kill it.
## Cause
1. Refresh fan-out: hundreds of resources each needing an API read, some paginated or throttled.
2. Provider API slowness: one data source or resource with an expensive query (list-all calls, cross-region reads).
3. Serialization: long `depends_on` chains or module dependencies forcing sequential operations that could be parallel.
## Confirmation
1. Run with `TF_LOG=INFO` and watch which provider calls take the longest. The log timestamps per API call; the slow ones stand out.
2. `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).
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
1. Refresh cost: split the config into smaller workspaces so each plan refreshes less. There is no flag that makes 2000 API reads fast.
2. 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.
3. Serialization: remove unnecessary `depends_on` (references already imply ordering). Break long module chains with data sources where the dependency is read-only.
4. `-parallelism` exists but raising it against a throttling API makes things worse. Fix the call pattern first.
## Verification
1. Time the plan before and after. "Faster" needs a number.
2. `terraform plan -refresh=false` vs full plan timings tell you whether refresh is still the dominant cost.
3. The plan output must be identical in content, just faster. Speedups that change the plan are not speedups.