Error: Backend configuration changed: re-run terraform init -reconfigure

TL;DR

You edited the backend block after terraform init already recorded the old settings. Terraform refuses to guess which config is authoritative. Re-run terraform init -reconfigure (same backend, new settings) or terraform init -migrate-state (moving state to a new backend).

The error

Error: Backend configuration changed

(Terraform shows the diff between the saved backend config and the current one.)

Steps to fix

1. Decide what changed: same backend with new settings (new bucket/key/region), or a genuinely different backend?

   • Expected: you know whether state needs to move.

2. Same backend, new settings:

   terraform init -reconfigure

   • Expected: Terraform has been successfully initialized!

   Moving state to a new backend:

   terraform init -migrate-state

   • Expected: Terraform prompts to copy state; answer yes after checking the target is empty.

3. Run terraform plan and confirm it sees the expected state.

   • Expected: plan reflects your real infrastructure, not an empty state.

When to use this

• Any command fails with Backend configuration changed after editing the terraform { backend ... } block or its -backend-config inputs.

When NOT to use this

• Backend initialization required means init never ran. If the new backend already has state, -migrate-state would overwrite it; use -reconfigure to just switch the pointer.

Compatibility

• All Terraform versions; -reconfigure and -migrate-state flags are stable.

Root cause

terraform init snapshots the backend configuration into .terraform/. Later commands compare the config against that snapshot; any difference aborts, because applying new backend settings silently could read or write the wrong state.

Edge cases

• In CI, backend settings often come from -backend-config flags; a changed flag value triggers this too.
• -reconfigure discards the old backend without moving state; if the old backend held the only copy, you lose access to it. Back up first with terraform state pull.
• Workspaces: reconfigure keeps the selected workspace if it exists in the new backend.

The mosip/infra Terraform workflow guide lists this under backend configuration errors: "Error: Backend configuration changed. Solution: Run terraform init to reinitialize backend configuration." It sits alongside state-lock and permission errors in the troubleshooting section, reflecting the real-world frequency of backend edits (bucket, key, region changes) breaking subsequent runs until re-initialization.