Introduction

Terraform stores backend metadata locally in .terraform/terraform.tfstate. If the S3 bucket, key, region, workspace prefix, or backend flags change, Terraform refuses to plan until the workspace is reinitialized. The important part is deciding whether the remote state moved or only the local backend settings changed.

Symptoms

  • terraform plan exits with Backend configuration changed
  • One engineer can still plan while another gets a reinitialization error
  • Recent changes touched backend blocks, partial config files, or CI init flags
  • The workspace may still point at an old bucket, key, or lock table

Common Causes

  • The backend block changed without rerunning terraform init
  • Backend values moved from HCL into -backend-config arguments or the reverse
  • The remote state location changed but the workspace still points at the old path
  • CI and local machines initialize the backend with different values

Step-by-Step Fix

  1. 1.Review exactly what changed in the backend settings
  2. 2.Compare the old and new backend values before choosing -reconfigure or -migrate-state.
bash
git diff -- '*.tf' '*.tfvars'
terraform init -reconfigure
  1. 1.**Use -reconfigure if only local metadata drifted**
  2. 2.If the bucket and state object did not move, reconfigure the workspace so Terraform forgets the stale local metadata and keeps using the same backend.
bash
terraform init -reconfigure
  1. 1.**Use -migrate-state only when the state location really changed**
  2. 2.If the bucket, key, or backend type changed, explicitly migrate the existing state instead of creating an empty backend.
bash
terraform init -migrate-state
  1. 1.Pull the state and run a clean plan
  2. 2.Confirm the workspace now points at the correct remote object before anyone applies changes.
bash
terraform state pull | head -20
terraform plan

Prevention

  • Standardize backend initialization flags in CI and local bootstrap docs
  • Review backend changes separately from normal resource changes
  • Require a state migration plan whenever backend buckets, keys, or prefixes move
  • Keep one clear source of truth for backend configuration inputs