What causes "workspace_key_prefix must not start with '/' or './'" in hashicorp/terraform?

Remove the leading '/' or './' from the prefix value.

workspace_key_prefix must not start with '/' or './'

Error message

workspace_key_prefix must not start with '/' or './'

What it means

Thrown by the ValidateFunc for the 'prefix' field in the OSS backend when the configured prefix starts with '/' or './'. The error message references 'workspace_key_prefix' (the field was likely renamed at some point), but it validates the 'prefix' attribute which controls the directory path for state files inside the OSS bucket.

Solutions

Remove the leading '/' or './' from the prefix value.
Use a simple directory-style prefix without path separators at the start, e.g. 'terraform/prod'.

Example fix

// before
terraform {
  backend "oss" {
    prefix = "/terraform/prod"
  }
}
// after
terraform {
  backend "oss" {
    prefix = "terraform/prod"
  }
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate OSS backend prefix before Terraform init
func validateOSSPrefix(prefix string) error {
    if strings.HasPrefix(prefix, "/") || strings.HasPrefix(prefix, "./") {
        return fmt.Errorf("prefix must not start with '/' or './'; use a flat key prefix like 'terraform/prod'")
    }
    return nil
}

Prevention

Use flat key-style prefixes without leading path separators (e.g. 'terraform/prod', not '/terraform/prod').
Remember OSS object keys are flat namespaces, not filesystem paths.
Keep the default 'env:' prefix if you don't need a custom directory structure.

When it happens

Trigger: ValidateFunc checks strings.HasPrefix(prefix, "/") or strings.HasPrefix(prefix, "./"). The user sets the 'prefix' backend attribute to a value like '/myproject' or './myproject'. The default value is 'env:'.

Common situations: Developer uses Unix-style absolute paths out of habit ('/terraform/state'). Developer uses relative path notation ('./prod'). Copy-paste from S3 backend configuration where leading slashes are tolerated differently. Misunderstanding that OSS prefixes are flat key prefixes, not filesystem paths.

Related errors

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

Appendix: source

Thrown at internal/backend/remote-state/oss/backend.go:161

				Description: "A custom endpoint for the OSS API",
				DefaultFunc: schema.MultiEnvDefaultFunc([]string{"ALICLOUD_OSS_ENDPOINT", "ALIBABA_CLOUD_OSS_ENDPOINT", "OSS_ENDPOINT"}, ""),
			},

			"bucket": {
				Type:        schema.TypeString,
				Required:    true,
				Description: "The name of the OSS bucket",
			},

			"prefix": {
				Type:        schema.TypeString,
				Optional:    true,
				Description: "The directory where state files will be saved inside the bucket",
				Default:     "env:",
				ValidateFunc: func(v interface{}, s string) ([]string, []error) {
					prefix := v.(string)
					if strings.HasPrefix(prefix, "/") || strings.HasPrefix(prefix, "./") {
						return nil, []error{fmt.Errorf("workspace_key_prefix must not start with '/' or './'")}
					}
					return nil, nil
				},
			},

			"key": {
				Type:        schema.TypeString,
				Optional:    true,
				Description: "The path of the state file inside the bucket",
				ValidateFunc: func(v interface{}, s string) ([]string, []error) {
					if strings.HasPrefix(v.(string), "/") || strings.HasSuffix(v.(string), "/") {
						return nil, []error{fmt.Errorf("key can not start and end with '/'")}
					}
					return nil, nil
				},
				Default: "terraform.tfstate",
			},
			"tablestore_instance_name": {

View on GitHub (pinned to d32a084675)