Error reading HCP Terraform Agent version. To proceed…

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

Thrown by Cloud.AssertImportCompatible when os.LookupEnv("TFC_AGENT_VERSION") reports the variable is not set. After confirming the API version supports import, the backend checks the HCP Terraform Agent version (>= 1.10 required); if the agent environment variable is absent, it cannot verify agent compatibility and refuses to proceed with import blocks.

Solutions

Upgrade the HCP Terraform Agent to version 1.10 or later, which exports TFC_AGENT_VERSION.
Remove import blocks from the config so the agent-version check is skipped entirely.
If using a custom agent image, ensure it sets TFC_AGENT_VERSION to a valid semver >= 1.10.
Verify the agent pod/container env is not being stripped by an orchestrator policy.

Example fix

// before - agent < 1.10 omits TFC_AGENT_VERSION, import blocks fail
import {
  to = aws_instance.example
  id = "i-1234567890abcdef0"
}
// after - upgrade agent to >= 1.10, or remove the import block

Defensive patterns

Strategy: validation

Validate before calling

// Verify the agent env var is set before remote execution with import blocks.
if _, ok := os.LookupEnv("TFC_AGENT_VERSION"); !ok {
    // refuse import blocks or surface early
}

Type guard

func agentVersionKnown() bool {
    _, ok := os.LookupEnv("TFC_AGENT_VERSION")
    return ok
}

Prevention

Deploy HCP Terraform Agent >= 1.10, which exports TFC_AGENT_VERSION.
In custom agent images, always set TFC_AGENT_VERSION to a valid semver.
Avoid import blocks until the agent pool is upgraded.

When it happens

Trigger: Fires only when: import blocks are present, TFC_RUN_ID is set (remote execution), and the API version already passed. The TFC_AGENT_VERSION env var is expected to be injected by the HCP Terraform Agent runtime; its absence means the agent is older than the version that sets it, or a custom/agentless execution environment.

Common situations: Running an HCP Terraform Agent older than 1.10 that does not export TFC_AGENT_VERSION; a custom runner/container that mimics the TFC execution env but omits the variable; agent image misconfigured to drop environment variables.

Related errors

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

Appendix: 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 d32a084675)