How to fix Error: State migration failed in Terraform

Before attempting migration, ensure both backends are accessible. Test your target backend credentials:

# For S3 backend
aws s3 ls s3://your-bucket-name/ --region us-east-1

# For Azure blob storage
az storage blob list --container-name tfstate --account-name youraccount

# For Google Cloud Storage
gsutil ls gs://your-terraform-state-bucket/

If any of these commands fail, fix the credential or connectivity issue before attempting migration again. Ensure your IAM user/service account has read, write, and delete permissions on the target backend.

State locks prevent concurrent access during migrations. Force unlock both backends if necessary:

# Check for locks
terraform state list

# Force unlock if a stale lock exists
terraform force-unlock <lock-id>

You can also manually remove lock files if available (e.g., .tflock files in Azure Blob Storage). Only force unlock if you're certain no one else is currently modifying the infrastructure.

If migration continues to fail, switch to -reconfigure mode instead. This tells Terraform to reinitialize without copying state:

terraform init -reconfigure

After this, you can manually migrate state using terraform state pull/push:

terraform state pull > /tmp/backup.tfstate
terraform state push /tmp/backup.tfstate

This two-step approach gives you more control and lets you verify each step. Always keep a backup like we did above.

If automatic migration fails, perform a manual state migration. First, initialize with the old backend configuration:

terraform init  # Uses old backend config
terraform state pull > /tmp/terraform.tfstate.backup

Then switch backend configuration and migrate manually:

terraform init -reconfigure  # Switch to new backend
terraform state push /tmp/terraform.tfstate.backup

Verify the state transferred correctly:

terraform state list
terraform state show

Keep the backup file indefinitely as a recovery point.

Large state files can timeout during migration. Retry with increased wait time:

terraform init -migrate-state -lock-timeout=15m

This tells Terraform to wait up to 15 minutes for locks to be released. If the state file is very large (over 100MB), split it by migrating resources in batches:

terraform state rm 'module.large_module[0]'
terraform init -migrate-state
terraform state push previous-backup.tfstate
terraform import module.large_module[0].aws_instance.main i-12345

After successful migration, verify the state wasn't corrupted:

terraform validate
terraform plan -out=tfplan

Review the plan output to ensure it accurately reflects your infrastructure. If the plan shows unexpected resource replacements or deletions, the migration may have introduced inconsistencies. In that case:

terraform state show <resource>
terraform state list | wc -l  # Count resources
terraform refresh

If problems persist, restore from the backup and contact HashiCorp support with the error logs.