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

TL;DR

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.

Error: Backend configuration changed

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

Steps

1. `

Error: Backend configuration changed

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

2. 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.

3. 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.

4. `-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.

## When to use

You are seeing this: Terraform stops rather than guess what you meant. Use this skill when you run into "Terraform: "Backend configuration changed" and picking -reconfigure vs -migrate-state".

## When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

## Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

## Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

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.