Error parsing TFC agent version. To proceed, please remove a

Error message

Error parsing TFC agent version. To proceed, please remove any import blocks from your config. Please report the following error to the OpenTofu team: %w

What it means

Version gate in Cloud.assertImportCompatible: import blocks are used in a remote run, TFC_AGENT_VERSION is set, but its value cannot be parsed as a semantic version by version.NewVersion. The wrapped err from the parser is included so you can see the offending input format.

Source

Thrown at internal/cloud/backend_plan.go:415

	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 OpenTofu team: %w", err)
		}
		desiredAPIVersion, _ := version.NewVersion("2.6")
		if currentAPIVersion.LessThan(desiredAPIVersion) {
			return fmt.Errorf("Import blocks are not supported in this version of the cloud backend. Please remove any import blocks from your config or upgrade the cloud backend.")
		}

		// Second, check the agent version is high enough.
		agentEnv, isSet := os.LookupEnv("TFC_AGENT_VERSION")
		if !isSet {
			return fmt.Errorf("Error reading TFC agent version. To proceed, please remove any import blocks from your config. Please report the following error to the OpenTofu team: TFC_AGENT_VERSION not present.")
		}
		currentAgentVersion, err := version.NewVersion(agentEnv)
		if err != nil {
			return fmt.Errorf("Error parsing TFC agent version. To proceed, please remove any import blocks from your config. Please report the following error to the OpenTofu team: %w", err)
		}
		desiredAgentVersion, _ := version.NewVersion("1.10")
		if currentAgentVersion.LessThan(desiredAgentVersion) {
			return fmt.Errorf("Import blocks are not supported in this version of the cloud backend 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 *backend.Operation, run *tfe.Run) error {
	logs, err := b.client.Plans.Logs(ctx, run.Plan.ID)
	if err != nil {
		return err
	}

	if b.View != nil {

View on GitHub (pinned to 3561785c48)

Solutions

Set TFC_AGENT_VERSION to a valid semantic version string that matches the deployed agent, e.g. 1.10.0
Remove the `import` blocks and use `tofu import` CLI instead
Use the official TFC/TFE agent image, which exports a well-formed version
Check for shell quoting/templating bugs in whatever injects the variable (trailing newline, quotes)

Example fix

# before (custom harness)
export TFC_AGENT_VERSION="latest"

# after
export TFC_AGENT_VERSION="1.10.0"

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Prevention

Inject TFC_AGENT_VERSION from the agent binary itself (agent --version), never from git shas or 'latest'
Validate env templates in CI with a schema/lint step
Quote and trim variables when templating harness env files

When it happens

Trigger: Import blocks + TFC_RUN_ID set + TFC_AGENT_VERSION present but malformed — e.g., 'unknown', 'latest', '1.10.x', a git sha, or a value with stray whitespace/quotes injected by a custom harness or CI templating.

Common situations: Custom agent wrappers exporting a placeholder like TFC_AGENT_VERSION=$(git rev-parse HEAD); CI systems quoting or interpolating the variable incorrectly; hand-crafted containers copying TFC env conventions imperfectly.

Related errors

AI-assisted analysis of opentofu/opentofu@3561785c48 (2026-08-15). Data as JSON: /api/errors/f776e010dbec9faf. Report an issue: GitHub.