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

Remove the leading '/' or './' from the prefix value (e.g. prefix = "terraform").

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

Error message

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

What it means

Returned by the ValidateFunc of the prefix (workspace_key_prefix) attribute of the oss backend when the value starts with '/' or './'. The prefix forms the directory path under which state files are stored, and a leading slash/dot-slash would create ambiguous absolute-style keys in OSS.

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 c9def3e214)

Solutions

Remove the leading '/' or './' from the prefix value (e.g. prefix = "terraform").
If you interpolate from a variable, trim the prefix: prefix = trim(var.state_prefix, "/").
Leave prefix unset to use the default "env:".

Example fix

# before
prefix = "/terraform-state"

# after
prefix = "terraform-state"

Defensive patterns

Strategy: validation

Validate before calling

func normalizePrefix(p string) (string, error) {
    if strings.HasPrefix(p, "/") || strings.HasPrefix(p, "./") {
        return "", fmt.Errorf("prefix must not start with '/' or './'")
    }
    return p, nil
}

Prevention

Use plain relative path segments for prefix.
trim() interpolated variables.
Leave unset to use 'env:'.

When it happens

Trigger: Configuring prefix = "/terraform" or prefix = "./env" (or via the prefix env var equivalent) in the terraform backend 'oss' block. The ValidateFunc runs at init/plan.

Common situations: Porting a config from the s3 backend where a leading slash was tolerated; using a path variable that includes a leading slash; copy-paste from file paths.

Related errors

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