Remote workspace Terraform version %q does not match local T

Error message

Remote workspace Terraform version %q does not match local Terraform version %q

What it means

A fallback guard in StateMgr() that fires when b.ignoreVersionConflict is false AND the remote workspace's pinned TerraformVersion differs from the locally running terraform binary version (and is not the pseudo-version "latest"). It prevents accidentally upgrading state with an unintended Terraform version. This is the coarse, last-resort check; the primary path is VerifyWorkspaceTerraformVersion().

Source

Thrown at internal/backend/remote/backend.go:701

		}

		workspace, err = b.client.Workspaces.Create(context.Background(), b.organization, options)
		if err != nil {
			return nil, diags.Append(fmt.Errorf("Error creating workspace %s: %v", name, err))
		}
	}

	// This is a fallback error check. Most code paths should use other
	// mechanisms to check the version, then set the ignoreVersionConflict
	// field to true. This check is only in place to ensure that we don't
	// accidentally upgrade state with a new code path, and the version check
	// logic is coarser and simpler.
	if !b.ignoreVersionConflict {
		wsv := workspace.TerraformVersion
		// Explicitly ignore the pseudo-version "latest" here, as it will cause
		// plan and apply to always fail.
		if wsv != tfversion.String() && wsv != "latest" {
			return nil, diags.Append(fmt.Errorf("Remote workspace Terraform version %q does not match local Terraform version %q", workspace.TerraformVersion, tfversion.String()))
		}
	}

	client := &remoteClient{
		client:       b.client,
		organization: b.organization,
		workspace:    workspace,

		// This is optionally set during Terraform Enterprise runs.
		runID: os.Getenv("TFE_RUN_ID"),
	}

	return &remote.State{
		Client: client,

		// client.runID will be set if we're running in a HCP Terraform
		// or Terraform Enterprise remote execution environment, in which
		// case we'll disable intermediate snapshots to avoid extra storage

View on GitHub (pinned to c9def3e214)

Solutions

Align versions: set the workspace's Terraform Version in the HCP/TFE UI to match your local binary, OR downgrade/upgrade your local terraform to match.
Set the workspace Terraform Version to "latest" so the check is skipped (line 700 explicitly allows it).
Use `-ignore-remote-version` flag, which sets ignoreVersionConflict=true and disables this guard (use only when you understand the state-format risk).
Pin `required_version` in configuration and agree on a single version across the team and workspace.

Example fix

// before - workspace pinned to 1.5.7, local binary is 1.7.0
// after - align by setting workspace version in UI:
//   Workspace Settings > General > Terraform Version = 1.7.0
// or locally run matching version, or use the flag:
$ terraform plan -ignore-remote-version

Defensive patterns

Strategy: validation

Validate before calling

// Compare local vs remote terraform version before state operations.
func versionsCompatible(local, remote string) bool {
    if remote == "" || remote == "latest" { return true }
    return local == remote
}

Type guard

func isVersionIgnorable(remoteVersion string) bool {
    return remoteVersion == "latest"
}

Try / catch

// Prefer VerifyWorkspaceTerraformVersion() which returns a warning
// (downgradeable) instead of this hard StateMgr error:
diags := b.VerifyWorkspaceTerraformVersion(wsName)
if diags.HasErrors() { /* handle, possibly prompt user */ }

Prevention

Pin the same Terraform version in the workspace and in your local/CI toolchain.
Add `required_version` to root modules to surface drift early.
Only use -ignore-remote-version when you intentionally accept state-format risk.
Set the workspace version to "latest" only if you accept non-deterministic versions.

When it happens

Trigger: Any state-manager operation (init/plan/apply via StateMgr) where the workspace's Terraform Version setting is pinned to e.g. 1.5.7 while the local binary is 1.7.0, and IgnoreVersionConflict() has not been called (it is called for remote Operation paths but not for the StateMgr/local paths).

Common situations: Team upgraded their local Terraform but the workspace is still pinned to an older version (or vice versa); CI pipeline uses a different terraform image version than the workspace default; a `required_version` constraint and the workspace version drifted.

Related errors

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/077248d03535ed3f. Report an issue: GitHub.