Once an apply is performed, the version of Terraform that performed the apply is saved in the state file. From that point, the
terraform command that performs subsequent operations on the state file must be the same version or a later version. By default, an earlier version of Terraform will not operate on a state file that was created with a later version, because this is not guaranteed to be safe.
It’s rarely necessary to downgrade Terraform, but in some unusual circumstances it may be required. There are a few options for performing a downgrade.
Roll back to a previous version of the state file
If an earlier version of the state file used an earlier version of Terraform, downgrade Terraform to the version specified in that state, and rerun any applies needed.
This is only possible when there is a relatively small difference between states, and downtime wouldn’t be incurred by any necessary resource re-creation or removal.
Manually edit the state file and specify a different Terraform version
Manual editing can be used even when there is a large number of changes, but there is no guarantee of a successful operation. Typically, a downgrade will not encounter issues as long as it is between minor versions (e.g., downgrading a state file from 0.11.5 to 0.11.3). Downgrading between major versions is strongly discouraged.
There are three steps involved when performing a manual edit of the state file:
- If you’re running in Terraform Enterprise (TFE), configure Terraform locally with a TFE backend.
- Back up a copy of the latest state file for safekeeping:
terraform state pull > latest-state.jsonfrom TFE, or manually make a safe copy locally or on another backend.
- Edit the state file, changing the
terraform_versionvalue to the desired earlier version.
For example, to downgrade from 0.11.5 to 0.11.3, change:
Once the change is made and the state file is saved, upload the state file into any backend to make it the latest state (see Creating a State Version Using the API for TFE to upload the edited state file to TFE).
Once this operation is complete, downgrade Terraform to the corresponding version (0.11.3 in this example) locally, as well as in Terraform Enterprise. Then run a normal plan operation to ensure that the desired results are produced.
If different, unexpected errors are encountered, they may be a result of the downgrade. Contact Hashicorp Support with a description of the steps you took and the issue you encountered so we can help.