🚨 OpenTofu Error: 'Backend configuration changed' — Cause, Fix, and Troubleshooting Guide

Overview

OpenTofu remembers the backend settings it initialized in .terraform/terraform.tfstate. When you edit the backend block — a new bucket, key, region, or lock table — the settings no longer match what was initialized, so OpenTofu stops and asks you to reinitialize, choosing whether to move existing state or start fresh:

Error: Backend configuration changed

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

If you wish to attempt automatic migration of the state, use "tofu init
-migrate-state".
If you wish to store the current configuration with no changes to the state,
use "tofu init -reconfigure".

Symptoms

• tofu plan/apply fails with Backend configuration changed.
• The message offers -migrate-state or -reconfigure.
• Appears right after editing the backend "s3"/gcs/azurerm block or its -backend-config.
• Common when promoting config between environments with different backends.

Common Root Causes

• Edited backend block — changed bucket, key, region, dynamodb_table, or prefix.
• Different -backend-config file/flags than the last init.
• Moved state to a new bucket/account intentionally.
• Templated backend values that resolved differently this run.
• Switched environments without passing the matching backend config.

How to diagnose

See what OpenTofu initialized versus what you now declare:

cat .terraform/terraform.tfstate | jq '.backend.config'
grep -A8 'backend' *.tf

Reproduce and read which decision OpenTofu wants:

tofu init 2>&1 | sed -n '1,20p'

Confirm access to the new backend target (S3 example):

aws s3 ls s3://example-tofu-state-new/ --region us-east-1

Fixes

Keep existing state — migrate it to the new backend settings:

tofu init -migrate-state

Start against the new backend without copying old state (only when that is truly what you want):

tofu init -reconfigure

Pass the matching -backend-config for the environment every time:

tofu init -backend-config=backend-prod.hcl -reconfigure

Verify the backend now matches and state is intact:

tofu state list | head

What to watch out for

• -migrate-state copies existing state to the new settings; -reconfigure ignores the old state. Choosing wrong can duplicate or abandon state.
• Keep per-environment backend values in backend-<env>.hcl files and pass them consistently.
• In CI, run tofu init -input=false with the correct backend config as a step before plan/apply.
• Back up remote state (bucket versioning) before migrating between backends.

Related

• OpenTofu Error: ‘Error acquiring the state lock’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Module not installed’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Backend initialization required’ — Cause, Fix, and Troubleshooting Guide