How to Downgrade a Provider Version in a Remote State Managed by Terraform Enterprise or HCP Terraform

Problem

After upgrading a Terraform provider and applying changes, attempting to downgrade to an older provider version for a resource fails with the following error. This occurs in workspaces where the state is managed by Terraform Enterprise or HCP Terraform.

Error: Resource instance managed by newer provider version

Cause

When you apply changes with a newer version of a provider, it may update the resource schema in the Terraform state file. This updated schema can be incompatible with older versions of the provider, preventing you from using the older version with the current state.

Solutions

If you cannot continue using the newer provider version, you can use one of the following solutions to downgrade. The correct solution depends on whether infrastructure changes were applied along with the provider upgrade.

Solution 1: Revert to a Previous State Version (No Infrastructure Changes)

This solution applies only if the provider version update was the only change applied to the state. This is the case if the terraform apply resulted in an empty apply or a "No changes" message.

In this scenario, you can revert to the state version from before the provider upgrade. You can accomplish this using one of two methods:

1. API: Create a new state version using the contents of the previous, compatible state file. For instructions, see How-to Create a State Version Using the API.
2. Terraform CLI: Use the terraform state pull and terraform state push commands to replace the current state with a previous version. For instructions, see Migrate Workspace State Using Terraform State Push / Pull.

Solution 2: Manually Re-import Resources (With Infrastructure Changes)

This solution is required if any infrastructure changes were applied with the newer provider version. The process involves removing the incompatible resources from the state and then re-importing them using the desired older provider version.

1. Configure the newer provider version: In your Terraform configuration, set the provider version constraint to the newer version that is compatible with your current state.
2. Remove resources from state: Follow the procedure to Remove Resources in a Remote State File Managed by HCP Terraform for each resource identified in the error message.
3. Configure the older provider version: Update your Terraform configuration to use the older, desired provider version.
4. Import resources into state: Follow the procedure to Import Resources into a Remote State Managed by HCP Terraform to bring the removed resources back into the state file. The import operation will use the older provider's schema, resolving the incompatibility.