What causes "key can not start and end with '/'" in hashicorp/terraform?

Use a clean object path with no leading or trailing slash, e.g. key = "terraform.tfstate".

key can not start and end with '/'

Error message

key can not start and end with '/'

What it means

Returned by the ValidateFunc of the key attribute of the oss backend when the state-file path starts or ends with '/'. A leading/trailing slash would resolve to a directory-like object key rather than the state file path; this validator blocks it at config time.

Source

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

				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": {
				Type:        schema.TypeString,
				Optional:    true,
				Description: "The instance name of tableStore table belongs",
				Default:     "",
			},

			"tablestore_table": {
				Type:        schema.TypeString,
				Optional:    true,
				Description: "TableStore table for state locking and consistency",
				Default:     "",
			},

View on GitHub (pinned to c9def3e214)

Solutions

Use a clean object path with no leading or trailing slash, e.g. key = "terraform.tfstate".
If you need subdirectories, separate with single slashes in the middle: key = "prod/web/terraform.tfstate".
Verify any interpolated variable does not add slashes.

Example fix

# before
key = "/env/prod/terraform.tfstate/"

# after
key = "env/prod/terraform.tfstate"

Defensive patterns

Strategy: validation

Validate before calling

func validateStateKey(k string) error {
    if strings.HasPrefix(k, "/") || strings.HasSuffix(k, "/") {
        return fmt.Errorf("key must not start or end with '/'")
    }
    return nil
}

Prevention

End the key with a filename like terraform.tfstate.
Never prefix the key with '/'.
Use single slashes between intermediate dirs only.

When it happens

Trigger: Setting key = "/terraform.tfstate" or key = "path/to/state/" in the oss backend block, or supplying such a value via the key schema default override.

Common situations: Copy-pasting an S3 key that had a leading slash; treating key as a directory; trailing slash typo.

Related errors

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