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

Not specified by the original author.

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.

Not specified by the original author.

Fix terraform "Backend initialization required, please run terraform init"

TL;DR: You are running plan or apply in a directory that was never initialized, or the backend config changed since the last init. Run terraform init. If you changed the backend block or its settings, run terraform init -reconfigure instead so it points at the right state without trying to migrate data.

The error

Error: Backend initialization required, please run "terraform init"

Steps

1. Confirm you are in the right directory and init has actually run: ls -la .terraform should exist. If the directory is missing, that is the whole story.

2. Run init:

   terraform init

   Expected output: Terraform has been successfully initialized!

3. If you recently edited the backend block (new bucket, new key, moved from local to remote), run:

   terraform init -reconfigure

   Expected: Successfully configured the backend "s3"! (or your backend) with no migration prompt. -reconfigure tells terraform to forget the old backend rather than copy state out of it.

4. Re-run terraform plan. Expected: the backend error is gone.

When this applies

• plan, apply, or validate fails with this error in a fresh checkout or after editing the backend block.
• You switched environments (dev to prod) and the backend key changed.

When it does NOT apply

• The error names a missing bucket or credentials instead (Failed to get existing workspaces, 403s). That is a backend config problem, not a missing init.
• You ran init -backend=false on purpose for a lint-only CI job. The error is expected there; run validate-only workflows instead.

Tool and version compatibility

• Terraform CLI 0.12+ through 1.x. Backend block behavior identical across versions.
• All backends: local, S3, GCS, AzureRM, Terraform Cloud.

Why it happens

Backend selection happens during init. Terraform stores which backend it configured in .terraform/. If that directory is missing (fresh clone, new machine) or the backend block no longer matches what init recorded, every command that touches state refuses to guess and asks you to init again.

Edge cases and pitfalls

• Plain terraform init after a backend change prompts to migrate state. In CI you usually do not want the interactive prompt; choose -reconfigure (discard old backend pointer) or -migrate-state (copy state to the new backend) deliberately.
• Switching state keys between environments (dev vs prod) triggers this normally. That is by design, not a bug.
• Azure backend users: a missing use_azuread_auth=true at init time surfaces as this error later. Pass it via -backend-config during init.

A reader hit Error: Backend initialization required after switching their backend key from dev to prod. The verified fix was terraform init -reconfigure, which repoints terraform at the new state key without attempting a migration, and the error cleared. A second confirmed case: a fresh checkout with no .terraform directory, fixed by a plain terraform init. Source: rickors560/terraform-guide troubleshooting guide, https://github.com/rickors560/terraform-guide/blob/HEAD/TROUBLESHOOTING.md

Not specified by the original author.

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.