State replace-provider in Terraform - Commands & Configuration

Introduction

Sometimes Terraform needs to update the provider used in the state file to a new source or version. The state replace-provider command helps fix the state by replacing the old provider with a new one without changing resources.

When a provider changes its source address and Terraform needs to update the state to match.

When migrating from a community provider to an official provider with a different name.

When upgrading Terraform configurations that require provider namespace changes.

When fixing state errors caused by provider mismatches after manual edits.

When consolidating multiple provider sources into a single consistent provider.

Commands

This command replaces all references to the old AWS provider source with the new provider source in the Terraform state. It updates the state without changing actual resources.

Terminal

terraform state replace-provider registry.terraform.io/hashicorp/aws registry.terraform.io/terraform-provider-aws/aws

Expected Output

Replaced provider registry.terraform.io/hashicorp/aws with registry.terraform.io/terraform-provider-aws/aws in 5 resource instances

Run terraform plan to verify that the state replacement did not cause any unexpected changes to your infrastructure.

Terminal

terraform plan

Expected Output

No changes. Infrastructure is up-to-date.

Key Concept

If you remember nothing else from this pattern, remember: terraform state replace-provider updates the provider source in the state file without changing resources.

Common Mistakes

Using incorrect provider source names in the replace-provider command.

Terraform will not find the provider to replace and the command will fail or do nothing.

Check the exact provider source addresses in your state and configuration before running the command.

Running replace-provider without backing up the state file.

If something goes wrong, you may lose track of your infrastructure state.

Always create a backup of your terraform.tfstate file before running state manipulation commands.

Summary

Use terraform state replace-provider to update provider source references in the state file.

Run terraform plan after replacement to confirm no infrastructure changes are planned.

Always verify provider source names and backup state before running the command.