Error parsing HCP Terraform Agent version. To proceed, pleas

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

Raised by AssertImportCompatible when TFC_AGENT_VERSION is set but cannot be parsed by version.NewVersion (e.g. non-semver, blank, or garbage). The backend cannot determine whether the agent supports import blocks.

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 c9def3e214)

Solutions

Set TFC_AGENT_VERSION to a valid semantic version string (e.g. 1.10.0).
Remove import blocks from the config and use 'terraform import'.
Rebuild the agent image with a correct version label and report the offending string to the Terraform team.

Example fix

# before
ENV TFC_AGENT_VERSION=latest
# after
ENV TFC_AGENT_VERSION=1.10.0

Defensive patterns

Strategy: validation

Validate before calling

v, ok := os.LookupEnv("TFC_AGENT_VERSION")
if ok {
    if _, err := version.NewVersion(v); err != nil {
        return fmt.Errorf("TFC_AGENT_VERSION=%q is not a valid semver", v)
    }
}

Type guard

func isParsableAgentVersion(v string) bool {
    _, err := version.NewVersion(v)
    return err == nil
}

Prevention

Set TFC_AGENT_VERSION to a strict semver (x.y.z).
Validate the env var in the agent container's entrypoint.
Avoid tagging agent images as 'latest'.

When it happens

Trigger: import blocks + remote run + agent env var present but malformed so that version.NewVersion(agentEnv) returns an error.

Common situations: Agent image sets TFC_AGENT_VERSION to a non-semver value ("latest", "v1", a git SHA, "1.10.0-dev+build"); manual env override with a typo; a CI runner that injects a wrong value.

Related errors

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