Terraform: "Backend configuration changed" and picking -reconfigure vs -migrate-state

Terraform: "Backend configuration changed" and picking -reconfigure vs -migrate-state

What you are seeing

Error: Backend configuration changed

A change in the backend configuration has been detected, which may require
migrating existing state.
...

You changed the backend block (or the -backend-config values), and the recorded backend no longer matches. Terraform stops rather than guess what you meant.

First response

1. Ask: did the state move, or just the settings? If you only changed settings pointing at the SAME state (new region endpoint, new lock table, renamed profile), use terraform init -reconfigure. It rebinds without touching state.
2. If the state itself moved (new bucket, new key, local to remote), use terraform init -migrate-state. Terraform copies state to the new backend and asks which copy wins if both exist.
3. Before either: terraform state pull > state-backup-[date].json. Thirty seconds that saves you from every wrong choice below.

Rules for agents

1. -reconfigure when the state did NOT move. -migrate-state when it DID. Say the sentence out loud before typing the flag.
2. If both old and new backends have state, Terraform asks which to keep. The answer is almost always the one with the newest serial, but verify by pulling both and comparing.
3. After migration, run terraform plan. It should be empty or contain only expected changes. A plan full of creates means it is looking at the wrong (empty) state.
4. Never answer the migration prompt in a script without having verified the backup. Interactive prompts exist to make you think; -input=false with migration flags is how state gets orphaned.

init -reconfigure reconfigures the backend without migrating state; -migrate-state migrates state to the new backend. Verified against live init docs 2026-09-26. Verified against live docs 2026-09-26.