Quick Answer
# Option 1: Migrate state to the new backend
terraform init -migrate-state
# Option 2: Start fresh (ignore existing state)
terraform init -reconfigure
⚠️ Use -migrate-state unless you’re certain you want to abandon the existing state.
The Error
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
"terraform init -migrate-state".
If you wish to store the current configuration with no changes to the state,
use "terraform init -reconfigure".
This appears when you change the backend block in your Terraform configuration.
Common Scenarios
Local → S3 Backend
# Before: local backend (default)
# No backend block — state in terraform.tfstate
# After: S3 backend
terraform {
backend "s3" {
bucket = "my-tf-state"
key = "prod/terraform.tfstate"
region = "us-east-1"
dynamodb_table = "terraform-locks"
encrypt = true
}
}
terraform init -migrate-state
# Terraform will ask: "Do you want to copy existing state to the new backend?"
# Answer: yes
S3 → Different S3 Key
# Changed the key path
terraform {
backend "s3" {
bucket = "my-tf-state"
key = "v2/prod/terraform.tfstate" # Changed from "prod/terraform.tfstate"
region = "us-east-1"
}
}
terraform init -migrate-state
# State migrates from old key to new key
S3 → Local (Moving State Back)
# Remove the backend block entirely
terraform {
# No backend — reverts to local
}
terraform init -migrate-state
# State downloaded from S3 to local terraform.tfstate
S3 → Different Backend (GCS, Azure)
# Before
terraform {
backend "s3" {
bucket = "my-tf-state"
key = "prod/terraform.tfstate"
region = "us-east-1"
}
}
# After
terraform {
backend "gcs" {
bucket = "my-tf-state-gcs"
prefix = "prod"
}
}
terraform init -migrate-state
# State migrates from S3 to GCS
Step-by-Step: Safe Backend Migration
1. Backup Current State
# Always backup before migration
terraform state pull > state-backup.json
2. Update Backend Configuration
Edit your .tf file with the new backend settings.
3. Initialize with Migration
terraform init -migrate-state
Terraform will:
- Read state from the old backend
- Write state to the new backend
- Ask for confirmation
4. Verify
# Check state is readable from new backend
terraform state list
# Plan should show no changes
terraform plan
# No changes. Your infrastructure matches the configuration.
5. Clean Up Old State (Optional)
# If migrated from local to S3, you can remove the local file
rm terraform.tfstate terraform.tfstate.backup
-migrate-state vs -reconfigure
| Flag | Effect |
|---|---|
-migrate-state | Copies existing state to the new backend |
-reconfigure | Configures new backend, ignores existing state |
# ✅ Safe — keeps your state
terraform init -migrate-state
# ⚠️ Dangerous — you lose track of existing resources
terraform init -reconfigure
# Terraform "forgets" about all managed resources
# Next plan will want to create everything from scratch
Use -reconfigure only when:
- You’re starting a brand new project
- You’ve manually copied state to the new backend already
- You’re switching to a backend that already has the correct state
Troubleshooting
“Error acquiring the state lock”
Error: Error acquiring the state lock
Lock Info:
ID: abc123-def456
Path: my-tf-state/prod/terraform.tfstate
Operation: OperationType
Another process holds the lock. Wait for it to finish, or force-unlock:
terraform force-unlock abc123-def456
terraform init -migrate-state
“Failed to read state from old backend”
# The old backend is unreachable — use reconfigure with manual state copy
# 1. Get state from old backend manually (S3 console, etc.)
# 2. Configure new backend
terraform init -reconfigure
# 3. Push state to new backend
terraform state push state-backup.json
“Backend configuration block has changed”
If you only changed backend variables (not the backend type), and the state is already where you want it:
terraform init -reconfigure
Partial Migration Failure
# If migration fails halfway:
# 1. Check if state exists in new backend
terraform state list
# 2. If empty, restore from backup
terraform state push state-backup.json
# 3. If state is in new backend, you're fine — continue working
Hands-On Courses
- Terraform for Beginners on CopyPasteLearn
- Terraform By Example — practical code examples
Conclusion
When Terraform says “backend configuration changed,” use terraform init -migrate-state to safely move your state. Always backup with terraform state pull before migrating. Use -reconfigure only when you don’t need to preserve existing state. The most common migration — local to S3 — takes under a minute and Terraform handles everything automatically.
