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

Introduction

This article details how to roll back to an older version of a Terraform provider after applying with a newer version.

Use Case

Applying with a newer version of a provider that introduced schema updates will make that resource state incompatible with an older version. This produces an error when attempting to downgrade:

Error: Resource instance managed by newer provider version

If it is not possible to use the newer provider version going forward, then the following procedure can be taken to downgrade. 

Procedure

If the change to the provider version was the only difference in the resource state since the last apply with the older version of the provider, i.e. if the apply was an empty apply or it was applied with "No changes. Your infrastructure matches the configuration.", then it is possible to make that older state file the current state file.

This can be accomplished via API:

• How-to Create a State Version Using the API

Or with Terraform state commands:

• Migrate Workspace State Using Terraform State Push / Pull

Otherwise, if there were any changes to resource state during or since the provider version upgrade, it will require removing the incompatible resources identified by the error from the state with the newer version of the provider, and importing them with the older version of the provider.

First, configure the newer version of the provider, then use the following to remove the incompatible resources from the state:

• How to Remove Resources in a Remote State File Managed by Terraform Cloud

Then, configure the older, desired version of the provider, and use the following to import the removed resources back into state with the compatible older version schema:

• How to Import Resources into a Remote State Managed by Terraform Cloud