An error occurred: unsupported state format version

Problem

When running a plan in a Terraform Enterprise workspace that uses Sentinel policy checks, the run fails with an error indicating an unsupported state format version. This typically occurs after upgrading the Terraform CLI version used in the workspace.

Cause

This error occurs when the Terraform CLI version configured for a workspace produces a state file version that the installed Terraform Enterprise instance does not support. Each release of Terraform Enterprise bundles support for specific Terraform CLI versions and their corresponding state file formats.

For example, Terraform Enterprise versions prior to v202107-1 do not support the 0.2 state format version introduced in Terraform CLI v1.0.1. Similarly, versions prior to v202111-1 do not support the 1.0 state format version from Terraform CLI v1.1.0.

While administrators can install more recent versions of Terraform CLI than those bundled with their Terraform Enterprise release, compatibility is not guaranteed.

Solutions

The recommended solution is to upgrade your Terraform Enterprise instance to a version that supports the Terraform CLI version you intend to use. Alternatively, you can downgrade the Terraform CLI version in the affected workspace.

Solution 1: Upgrade Terraform Enterprise

Upgrade your Terraform Enterprise instance based on the Terraform CLI version causing the error.

• For Terraform CLI v1.0.1 - v1.0.11: Upgrade Terraform Enterprise to version v202107-1 or later. This version added support for the 0.2 state format version, as noted in the release notes.
• For Terraform CLI v1.1.0 - v1.1.6: Upgrade Terraform Enterprise to version v202111-1 or later. This version added support for the 1.0 state format version, as noted in the release notes.

For guidance on the upgrade process, refer to the Upgrading Terraform Enterprise documentation.

Solution 2: Downgrade the Workspace Terraform Version

If you cannot upgrade Terraform Enterprise, downgrade the Terraform Version in the workspace settings to a version compatible with your current Terraform Enterprise installation.

Additional Information

State Format Version Reference

• Terraform CLI v0.15.0 - v1.0.0: State Format Version 0.1
• Terraform CLI v1.0.1 - v1.0.11: State Format Version 0.2
• Terraform CLI v1.1.0 - v1.1.6: State Format Version 1.0

You can identify the state format version of a plan file by running the terraform show -json command and inspecting the format_version key.

$ terraform show -json
{
  "format_version": "1.0",
  "terraform_version": "1.1.6",
  "values": {
    "root_module": {
      "resources": [
        {
          "address": "null_resource.cluster",
          "mode": "managed",
          "type": "null_resource",
          "name": "cluster",
          "provider_name": "registry.terraform.io/hashicorp/null",
          "schema_version": 0,
          "values": {
            "id": "2266218645750406959",
            "triggers": null
          },
          "sensitive_values": {}
        }
      ]
    }
  }
}