Error reading HCP Terraform Agent version. To proceed, pleas

Error message

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.

What it means

Raised by AssertImportCompatible when import blocks are present in a remote run and the TFC_AGENT_VERSION environment variable is not set at all. The backend needs the agent version to verify it supports import (>= 1.10); absence prevents the check.

Source

Thrown at internal/cloud/backend_plan.go:354

// driven import and the version of the agent or API is too low to support it.
func (b *Cloud) AssertImportCompatible(config *configs.Config) error {
	// Check TFC_RUN_ID is populated, indicating we are running in a remote TFC
	// execution environment.
	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 {

View on GitHub (pinned to c9def3e214)

Solutions

Remove import blocks from the config and import imperatively.
Update/recreate the HCP Terraform Agent so that TFC_AGENT_VERSION is exported (use an agent image >= 1.10 that sets the variable).
Run the operation with local execution instead of the agent.

Example fix

# before: agent image missing the variable (env shows nothing)
# after: ensure the agent Dockerfile / entrypoint exports it
ENV TFC_AGENT_VERSION=1.10.0

Defensive patterns

Strategy: validation

Validate before calling

// Detect missing agent version before running.
if _, ok := os.LookupEnv("TFC_AGENT_VERSION"); !ok && hasImportBlocks(cfg) {
    return fmt.Errorf("TFC_AGENT_VERSION unset; cannot verify agent import support")
}

Prevention

Bake TFC_AGENT_VERSION into the agent image entrypoint.
Use a supported (>= 1.10) agent image.
Test import-block configs in a staging workspace first.

When it happens

Trigger: config has import blocks, TFC_RUN_ID set, API version OK, but os.LookupEnv("TFC_AGENT_VERSION") returns isSet == false.

Common situations: Running on a custom or misconfigured HCP Terraform Agent image where the agent startup does not export TFC_AGENT_VERSION; older agent versions that predate the variable; importing blocks into a workspace whose agent pool runs such an image.

Related errors

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