Error parsing HCP Terraform Agent version. To proceed…

Error message

Error parsing HCP Terraform Agent version. To proceed, please remove any import blocks from your config. Please report the following error to the Terraform team: %s

What it means

Thrown by Cloud.AssertImportCompatible when os.LookupEnv confirms TFC_AGENT_VERSION is set but version.NewVersion(agentEnv) fails to parse it. The value must be a valid semver-like string; garbage, empty-after-set, or non-numeric content causes the parse error.

Solutions

Set TFC_AGENT_VERSION to a valid semver string (e.g. '1.10.0') in the agent runtime.
Upgrade to an official HCP Terraform Agent release that exports a correctly formatted version.
Remove import blocks to bypass the check.
Inspect the raw TFC_AGENT_VERSION value in the agent container and correct the export script.

Example fix

// before - non-semver agent version breaks the parse
// TFC_AGENT_VERSION=latest  (or a git sha)
// after - use a valid semver
// TFC_AGENT_VERSION=1.10.0

Defensive patterns

Strategy: validation

Validate before calling

// Validate the agent version string is parseable semver.
if v, err := version.NewVersion(os.Getenv("TFC_AGENT_VERSION")); err != nil {
    return fmt.Errorf("TFC_AGENT_VERSION unparseable: %w", err)
}

Type guard

func agentVersionValid() bool {
    _, err := version.NewVersion(os.Getenv("TFC_AGENT_VERSION"))
    return err == nil
}

Prevention

Set TFC_AGENT_VERSION to a release semver (e.g. 1.10.0), never 'latest' or a git SHA.
Use official agent images that format the version correctly.
Add a startup check in custom agent images that fails fast on a bad version env.

When it happens

Trigger: TFC_AGENT_VERSION is present but contains a non-parseable string (e.g. 'latest', 'unknown', a git SHA, an empty string from a broken export, or a version with invalid characters). version.NewVersion requires a recognized semver-ish format.

Common situations: Custom agent image that sets TFC_AGENT_VERSION to a build tag or commit hash instead of a release semver; a CI pipeline that writes a non-semver into the env; an agent that exports a pre-release string the parser rejects.

Related errors

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/6b7007ceec38a988. Report an issue: GitHub.

Appendix: source

Thrown at internal/cloud/backend_plan.go:358

	if len(config.Module.Import) > 0 && os.Getenv("TFC_RUN_ID") != "" {
		// First, check the remote API version is high enough.
		currentAPIVersion, err := version.NewVersion(b.client.RemoteAPIVersion())
		if err != nil {
			return fmt.Errorf("Error parsing remote API version. To proceed, please remove any import blocks from your config. Please report the following error to the Terraform team: %s", err)
		}
		desiredAPIVersion, _ := version.NewVersion("2.6")
		if currentAPIVersion.LessThan(desiredAPIVersion) {
			return fmt.Errorf("Import blocks are not supported in this version of Terraform Enterprise. Please remove any import blocks from your config or upgrade Terraform Enterprise.")
		}

		// Second, check the agent version is high enough.
		agentEnv, isSet := os.LookupEnv("TFC_AGENT_VERSION")
		if !isSet {
			return fmt.Errorf("Error reading HCP Terraform Agent version. To proceed, please remove any import blocks from your config. Please report the following error to the Terraform team: TFC_AGENT_VERSION not present.")
		}
		currentAgentVersion, err := version.NewVersion(agentEnv)
		if err != nil {
			return fmt.Errorf("Error parsing HCP Terraform Agent version. To proceed, please remove any import blocks from your config. Please report the following error to the Terraform team: %s", err)
		}
		desiredAgentVersion, _ := version.NewVersion("1.10")
		if currentAgentVersion.LessThan(desiredAgentVersion) {
			return fmt.Errorf("Import blocks are not supported in this version of the HCP Terraform Agent. You are using agent version %s, but this feature requires version %s. Please remove any import blocks from your config or upgrade your agent.", currentAgentVersion, desiredAgentVersion)
		}
	}
	return nil
}

// renderPlanLogs reads the streamed plan JSON logs and calls the JSON Plan renderer (jsonformat.RenderPlan) to
// render the plan output. The plan output is fetched from the redacted output endpoint.
func (b *Cloud) renderPlanLogs(ctx context.Context, op *backendrun.Operation, run *tfe.Run) error {
	logs, err := b.client.Plans.Logs(ctx, run.Plan.ID)
	if err != nil {
		return err
	}

	if b.CLI != nil {

View on GitHub (pinned to d32a084675)