Error: Backend configuration changed

Terraform’s “Backend configuration changed” error occurs when you modify the backend block without reinitializing. Run terraform init -reconfigure to fix it.

What It Means

The backend determines where Terraform stores its state file — locally, in S3, in Consul, or in Terraform Cloud. When you change backend configuration, Terraform detects the drift and refuses to proceed until you run terraform init to confirm the change.

Why It Happens

• You changed the backend block from local to remote (e.g. S3, AzureRM, GCS).
• You modified backend settings such as bucket name, key prefix, or region.
• You switched from one remote backend to another.
• The .terraform directory was deleted after the backend was configured.
• Team members pushed a different backend configuration than what you have locally.

How to Fix It

Step 1: Run terraform init with -reconfigure

The -reconfigure flag tells Terraform to forget the previous backend and set up the new one without migrating existing state:

terraform init -reconfigure

This is safe when you have no existing state to preserve or you want to start fresh.

Step 2: Migrate state to the new backend

If you want to copy your existing state to the new backend:

terraform init -migrate-state

Terraform will prompt for confirmation before copying the state file. Use -force-copy to skip the prompt in automation:

terraform init -migrate-state -force-copy

Step 3: Verify the backend configuration

After initialization, check which backend is active:

terraform state pull > /dev/null && echo "Backend OK"

Or inspect the .terraform/terraform.tfstate file to see the backend configuration.

Step 4: Backup your state before migration

Always back up your state before making backend changes:

cp terraform.tfstate terraform.tfstate.backup.$(date +%Y%m%d)

Step 5: Example S3 backend migration

If you’re moving from local state to S3:

terraform {
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "prod/terraform.tfstate"
    region = "us-east-1"
  }
}

Then run:

terraform init -migrate-state