⚙️ OpenTofu Error: 'Backend initialization required, please run tofu init'

Exact Error Message

╷
│ Error: Backend initialization required: please run "tofu init"
│
│ Reason: Backend configuration block has changed
│
│ The "backend" is the interface that OpenTofu uses to store state and
│ perform operations. When you change the configured backend, you must run
│ "tofu init" to reconfigure or migrate your state.
│
│ If you'd like to reconfigure and ignore any existing state, run
│ "tofu init -reconfigure".
╵

You will see this when running tofu plan, tofu apply, or tofu state after editing the backend block or its settings.

What It Means

OpenTofu stores a snapshot of your backend configuration in .terraform/ the first time you initialize. On every later command it compares the current backend block against that snapshot. When they differ — a changed bucket, key, region, or a switch from local to s3 — OpenTofu refuses to run operations until you explicitly reinitialize, so it never silently reads or writes state in the wrong place.

This is a safety gate, not a corruption. The state itself is intact; OpenTofu just needs you to decide whether to migrate the existing state to the new backend or reconfigure without migrating.

Common Causes

• You edited the backend block (new bucket, key, prefix, region, or workspace settings).
• You switched backend types (for example local to s3, or s3 to gcs).
• You added -backend-config values that differ from the last initialization.
• The .terraform/ directory was deleted or never created in this checkout (fresh clone, clean CI runner).
• A CI cache carried a stale backend snapshot that no longer matches the config.

Diagnostic Commands

Confirm which backend the configuration now declares:

tofu providers

See what changed against the last run without altering anything:

git diff -- '*.tf' | grep -A8 backend

Attempt a plan to reproduce the exact reason line (“Backend configuration block has changed”):

tofu plan

Inspect the last recorded backend snapshot, if present:

cat .terraform/terraform.tfstate 2>/dev/null | head -n 20

Step-by-Step Resolution

1. Decide your intent: migrate existing state to the new backend, or reconfigure and start fresh against the new backend. This choice drives which flag you use.

2. To migrate the existing state (the usual case when moving buckets or backend types), run init and accept the copy prompt:

tofu init -migrate-state

Do you want to copy existing state to the new backend?
  Enter a value: yes

3. To point at a new, already-correct backend without copying old state (for example a fresh workspace), reconfigure instead:

tofu init -reconfigure

4. On a clean CI runner where .terraform/ simply does not exist yet, a plain init is enough — pass any dynamic settings with -backend-config:

tofu init -backend-config=bucket=acme-tfstate -backend-config=key=prod/network.tfstate

5. If init complains it cannot prompt in automation, supply the migration choice non-interactively:

tofu init -migrate-state -input=false

6. Verify the backend is initialized and operations run again:

tofu plan

OpenTofu has been successfully initialized!
No changes. Your infrastructure matches the configuration.

Before migrating a production backend, snapshot the current state (tofu state pull > backup.tfstate) so you can recover if the copy is interrupted. If you are standardizing backend blocks across many stacks, the OpenTofu backend prompts can generate a consistent template.

Prevention

• Treat backend changes as deliberate migrations: change the block, then immediately run tofu init -migrate-state and commit together.
• Always back up state with tofu state pull before switching backends or buckets.
• Use -backend-config files for environment-specific values so the backend block itself stays stable across environments.
• In CI, run tofu init as the first step of every job so a clean runner is always initialized before plan/apply.
• Understand the difference: -migrate-state copies state to the new backend; -reconfigure discards the association and does not copy.

Related Errors

• Initialization required. Please see the error message above — a broader init-needed message covering providers and modules too.
• Error loading state: ... — the backend is initialized but the state object itself cannot be read.
• Backend configuration changed (partial config) — the same trigger caused by differing -backend-config values.
• Error acquiring the state lock — a post-init locking problem, not an initialization one.

Frequently Asked Questions

What is the difference between -migrate-state and -reconfigure? -migrate-state copies your existing state into the new backend; -reconfigure re-associates with the new backend without copying, so use it only when the new backend already holds the state you want.

Will reinitializing lose my state? Not if you use -migrate-state, which copies it; pull a backup first with tofu state pull > backup.tfstate for extra safety before any migration.

Why does this happen on a fresh CI runner? The runner has no .terraform/ snapshot, so OpenTofu cannot confirm the backend matches; running tofu init at the start of the job resolves it.

How do I answer the migration prompt in automation? Add -input=false alongside -migrate-state (or -reconfigure) so init proceeds without an interactive prompt. For more backend and state fixes, see the OpenTofu guides.