hashicorp/terraform · error

your version of Terraform Enterprise does not support key-va

Error message

your version of Terraform Enterprise does not support key-value tags. Please upgrade Terraform Enterprise to a version that supports this feature or use set type tags instead.

What it means

ErrCloudDoesNotSupportKVTags is returned when the cloud backend detects that a workspace tag mapping specifies a key-value pair (value != "") but the connected Terraform Enterprise instance does not support tag bindings (supportsKVTags is false). HCP Terraform and recent TFE versions support KV tag bindings; older TFE does not.

Source

Thrown at internal/cloud/backend.go:50

	"github.com/hashicorp/terraform/internal/plans"
	"github.com/hashicorp/terraform/internal/states/statemgr"
	"github.com/hashicorp/terraform/internal/terraform"
	"github.com/hashicorp/terraform/internal/tfdiags"
	tfversion "github.com/hashicorp/terraform/version"

	backendLocal "github.com/hashicorp/terraform/internal/backend/local"
)

const (
	defaultHostname    = "app.terraform.io"
	defaultParallelism = 10
	tfeServiceID       = "tfe.v2"
	headerSourceKey    = "X-Terraform-Integration"
	headerSourceValue  = "cloud"
	genericHostname    = "localterraform.com"
)

var ErrCloudDoesNotSupportKVTags = errors.New("your version of Terraform Enterprise does not support key-value tags. Please upgrade Terraform Enterprise to a version that supports this feature or use set type tags instead.")

// Cloud is an implementation of backendrun.OperationsBackend in service of the HCP Terraform or Terraform Enterprise
// integration for Terraform CLI. This backend is not intended to be surfaced at the user level and
// is instead an implementation detail of cloud.Cloud.
type Cloud struct {
	// CLI and Colorize control the CLI output. If CLI is nil then no CLI
	// output will be done. If CLIColor is nil then no coloring will be done.
	CLI      cli.Ui
	CLIColor *colorstring.Colorize

	// ContextOpts are the base context options to set when initializing a
	// new Terraform context. Many of these will be overridden or merged by
	// Operation. See Operation for more details.
	ContextOpts *terraform.ContextOpts

	// client is the HCP Terraform or Terraform Enterprise API client.
	client *tfe.Client

View on GitHub (pinned to c9def3e214)

Solutions

1. Upgrade the Terraform Enterprise deployment to a version that supports key-value tag bindings.
2. Switch the tags config to key-only set tags (e.g. tags = ["Environment:prod"] as a single string, or set-type tags) which work on older TFE.
3. Move the workspace to HCP Terraform, which supports KV tags.

Example fix

// before
workspaces {
  tags = {
    Environment = "prod"
  }
}
// after (set-type tags, works on older TFE)
workspaces {
  tags = ["Environment:prod"]
}

# Before applying, check that KV tags are only used on supported backends.
# Use set-type tags to stay compatible with older TFE:
workspaces { tags = ["Environment:prod"] }

if _, err := b.configureCloud(ctx); err != nil {
    if errors.Is(err, cloud.ErrCloudDoesNotSupportKVTags) {
        // prompt user to switch to set-type tags or upgrade TFE
        return fmt.Errorf("switch to key-only tags or upgrade TFE: %w", err)
    }
    return err
}

When it happens

Trigger: Configuring workspaces { tags = { Environment = "prod" } } against a Terraform Enterprise deployment whose version predates tag-binding support; workspaceTagsRequireUpdate() finds a non-empty value and result.supportsKVTags is false.

Common situations: Upgrading config to use key-value tags while still on an older self-hosted TFE; pointing a config at a TFE instance that hasn't been upgraded.

Related errors

• operation timed out
• {joined API error payload}
• {r.Status}
• backend does not support key/value tags. Try using key-only
• error updating workspace %q tags: %w

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