hashicorp/terraform · error

Error parsing remote API version. To proceed, please remove…

Error message

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

What it means

Thrown by Cloud.AssertImportCompatible when version.NewVersion(b.client.RemoteAPIVersion()) returns an error. The backend asks the TFE/HCP API for its version string and tries to parse it; if the string is empty, malformed, or non-semver, parsing fails. This gates configuration-driven import blocks (added in Terraform 1.5+) in remote execution.

Solutions

  1. Remove import blocks from the configuration to bypass the compatibility check entirely.
  2. Upgrade the Terraform Enterprise installation so it reports a parseable API version (>= 2.6 ideally).
  3. Inspect b.client.RemoteAPIVersion() output (enable TRACE/DEBUG logging) to see the malformed string and fix the proxy/gateway mangling it.
  4. Ensure no middlebox between the agent and TFE strips the version header.

Example fix

// before - config has import blocks but TFE returns no version
import {
  to = aws_instance.example
  id = "i-1234567890abcdef0"
}
// after - remove import blocks for this TFE version, or upgrade TFE
Defensive patterns

Strategy: validation

Validate before calling

// Pre-check the API version string is parseable before relying on it.
if _, err := version.NewVersion(b.client.RemoteAPIVersion()); err != nil {
    // log and either skip import blocks or surface a clearer error
}

Type guard

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

Try / catch

v, err := version.NewVersion(b.client.RemoteAPIVersion())
if err != nil {
    return fmt.Errorf("unparseable remote API version %q: %w", b.client.RemoteAPIVersion(), err)
}

Prevention

When it happens

Trigger: Only fires when config.Module.Import has entries AND TFC_RUN_ID is set (i.e. running inside a remote TFC/TFE execution environment). The RemoteAPIVersion() call returns something version.NewVersion cannot parse — an older TFE that doesn't report a version, a custom API gateway stripping the version header, or a malformed response.

Common situations: Old self-hosted Terraform Enterprise that predates the API-version endpoint; a reverse proxy/load balancer in front of TFE stripping the version response; import blocks used against a TFE version that lacks the version-reporting capability.

Related errors

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

Appendix: source

Thrown at internal/cloud/backend_plan.go:344

	// run, but the user still needs to see why, so this always renders.
	if err := b.renderTFPolicyEvaluations(stopCtx, r,
		tfe.TFPolicyEvaluationStageTypeInit, tfe.TFPolicyEvaluationStageTypePlan); err != nil {
		return r, err
	}

	return r, nil
}

// AssertImportCompatible errors if the user is attempting to use configuration-
// 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)

View on GitHub (pinned to d32a084675)