{"record":{"id":"32b27b61e9ebccc3","repo":"hashicorp/terraform","slug":"error-checking-remote-terraform-version","errorCode":null,"errorMessage":"Error checking remote Terraform version","messagePattern":"Error checking remote Terraform version","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/state_meta.go","lineNumber":54,"sourceCode":"\t\trealState = statemgr.NewFilesystem(c.statePath)\n\t} else {\n\n\t\t// Load the backend\n\t\tb, diags := c.backend(\".\", view)\n\t\tif diags.HasErrors() {\n\t\t\treturn nil, diags.Err()\n\t\t}\n\n\t\tworkspace, err := c.Workspace()\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\n\t\t// Check remote Terraform version is compatible\n\t\tremoteVersionDiags := c.remoteVersionCheck(b, workspace)\n\t\tc.showDiagnostics(remoteVersionDiags)\n\t\tif remoteVersionDiags.HasErrors() {\n\t\t\treturn nil, fmt.Errorf(\"Error checking remote Terraform version\")\n\t\t}\n\n\t\t// Get the state\n\t\ts, sDiags := b.StateMgr(workspace)\n\t\tif sDiags.HasErrors() {\n\t\t\treturn nil, sDiags.Err()\n\t\t}\n\n\t\t// Get a local backend\n\t\tlocalRaw, backendDiags := c.Backend(&BackendOpts{ForceLocal: true})\n\t\tif backendDiags.HasErrors() {\n\t\t\t// This should never fail\n\t\t\tpanic(backendDiags.Err())\n\t\t}\n\t\tlocalB := localRaw.(*backendLocal.Local)\n\t\t_, stateOutPath, _ = localB.StatePaths(workspace)\n\t\tif err != nil {\n\t\t\treturn nil, err","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/command/state_meta.go#L36-L72","documentation":"Thrown by StateMeta after remoteVersionCheck reports errors. When a state command uses a remote backend that implements BackendWithRemoteTerraformVersion (e.g. HCP Terraform / TFE / cloud), Terraform calls VerifyWorkspaceTerraformVersion to compare the CLI version against the version recorded in the remote workspace state. If they conflict and the user did not pass -ignore-remote-version, the backend emits error diagnostics and this generic message is returned. Note the real detail is shown separately via showDiagnostics before this summary error.","triggerScenarios":"Running `terraform state list|show|mv|rm|push` (any command using StateMeta.State) against an HCP Terraform / TFE / cloud workspace whose recorded terraform_version is newer than or otherwise incompatible with the local CLI binary, without passing -ignore-remote-version. Triggered inside meta_backend.go remoteVersionCheck when VerifyWorkspaceTerraformVersion returns error-severity diags.","commonSituations":"Downgrading the local CLI after a teammate upgraded the workspace; CI pinned to an older Terraform while the workspace was touched by a newer one; switching between Terraform and OpenTofu against the same HCP workspace; workspace terraform_version auto-bumped on first apply by a newer runner.","solutions":["Upgrade the local CLI to match the workspace's recorded terraform_version (shown in the preceding diagnostic).","Pass -ignore-remote-version to override the check if you accept the risk: `terraform state list -ignore-remote-version`.","Pin the HCP/TFE workspace terraform_version to match your CI CLI version.","Inspect the real version conflict in the diagnostic printed before this summary line and resolve the actual mismatch."],"exampleFix":"# before\nterraform state list\n# Error checking remote Terraform version\n\n# after\nterraform state list -ignore-remote-version","handlingStrategy":"validation","validationCode":"// before invoking state commands against a remote workspace,\n// compare local CLI version to the workspace's terraform_version.\nfunc versionCompatible(local, remote string) bool {\n    lv, err := semver.Parse(local)\n    if err != nil { return false }\n    rv, err := semver.Parse(remote)\n    if err != nil { return false }\n    // allow same major.minor; error otherwise unless caller overrides\n    return lv.Major == rv.Major && lv.Minor == rv.Minor\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin CI Terraform CLI version to match the HCP/TFE workspace terraform_version.","Standardize one Terraform version across the team and the remote workspace.","Use -ignore-remote-version deliberately only when you understand the risk.","Audit workspace terraform_version after every CLI upgrade."],"tags":["state","remote-backend","version-conflict","hcp-terraform"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}