hashicorp/terraform · error

your version of Terraform Enterprise does not support…

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

Exported sentinel ErrCloudDoesNotSupportKVTags (cloud/backend.go:50). The cloud backend's workspaceTagsRequireUpdate (cloud/backend.go:1233-1237) returns it when the configured workspace tags include a key=value pair but the connected TFE server does not support tag bindings (supportsKVTags == false) — i.e. an older Terraform Enterprise. backend.go:841 wraps it with the suggestion to use key-only tags or upgrade TFE.

Solutions

1. Upgrade your Terraform Enterprise to a version that supports key-value tag bindings.
2. Switch the backend tag config to set-type (key-only) tags: `workspaces { tags = ["env:prod"] }`.
3. Remove the value portion of the offending tags so only keys remain.

Example fix

# before
workspaces {
  name = "app"
  tags = { Environment = "prod" }
}
# after (set-type tags)
workspaces {
  name = "app"
  tags = ["Environment:prod"]
}

// Before apply, confirm TFE supports tag bindings if you use KV tags.
// Check server version >= the tag-bindings release, or keep tags key-only.
ws, err := b.client.Workspaces.Read(ctx, org, name)
if !supportsKVTags(ws) && hasKVTags(config.Tags) {
    return ErrCloudDoesNotSupportKVTags
}

// Use set-type (key-only) tags when TFE version is unknown/old.
workspaces { tags = ["env:prod"] } // string set form, no values

if errors.Is(err, cloud.ErrCloudDoesNotSupportKVTags) {
    // downgrade config to set-type tags and re-plan, or upgrade TFE
}

When it happens

Trigger: Using the 'cloud' backend with `workspaces { tags = { Environment = "prod" } }` (key-value form) against a Terraform Enterprise installation older than the version that introduced tag bindings. workspaceTagsRequireUpdate detects a non-empty value with supportsKVTags==false and sets err = ErrCloudDoesNotSupportKVTags.

Common situations: Self-hosted TFE behind the supported feature set. Pointing the cloud backend at an older TFE while your config uses modern KV tags. Migrating a workspace from HCP Terraform to an older TFE.

Related errors

• tag elements must be strings
• tag object values must be strings
• backend does not support key/value tags. Try using key-only…
• error loading config with snapshot
• error updating workspace

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

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