Terraform init flags: -upgrade, -reconfigure, -migrate-state mean different things

TL;DR: Agents cargo-cult terraform init flags and corrupt backend bindings. Each flag answers a different question; using the wrong one either does nothing or moves your state. Use when the backend settings changed but the state stays where it is. Never -migrate-state without a backup of the current state (terraform state pull > backup.json first).

Why

terraform init does two jobs: install providers/modules, and configure the backend. Its flags target one job each, and mixing them up is how backends get rebound to the wrong state or provider upgrades happen by accident.

The flags

1. Plain terraform init. Installs what is missing, configures the backend if not already configured. Safe to rerun; it changes nothing once set up.
2. -upgrade. Re-resolves providers and modules to the newest allowed versions and rewrites the lock file. This is a deliberate upgrade action, not hygiene.
3. -reconfigure. Discards the existing backend configuration and reconfigures from scratch, without migrating state. Use when the backend settings changed but the state stays where it is. The old state file is left behind, not moved.
4. -migrate-state. Moves state from the old backend to the new one when the backend block changed. Terraform asks which state to keep when both exist.

Rules for agents

1. Backend block changed? You need -reconfigure or -migrate-state. Plain init will error telling you exactly this; read the error instead of guessing flags.
2. Never -migrate-state without a backup of the current state (terraform state pull > backup.json first).
3. -upgrade in CI is a policy decision, not a default. Pin it behind an explicit upgrade job.
4. If init says the backend config changed and you did not change it, stop. Something or someone else did; find out what before proceeding.

When to use this

• This covers exactly what the title says: Terraform init flags.
• You are setting this up for the first time, or auditing an existing setup.
• You want the key gotchas in one place before you start.

When not to use this

• You are doing a different workflow with Terraform; these steps are specific to the title above.
• You need the full reference docs; this is the short path, not the manual.

terraform init flags: -upgrade upgrades modules/providers; -reconfigure reconfigures the backend ignoring prior config; -migrate-state migrates state to a new backend. Verified against live init command docs 2026-09-26. Verified against live docs 2026-09-26.