{"record":{"id":"fb0a5f5a81d1ae01","repo":"hashicorp/terraform","slug":"workspace-key-prefix-must-not-start-with-or","errorCode":null,"errorMessage":"workspace_key_prefix must not start with '/' or './'","messagePattern":"workspace_key_prefix must not start with '/' or '\\./'","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote-state/oss/backend.go","lineNumber":161,"sourceCode":"\t\t\t\tDescription: \"A custom endpoint for the OSS API\",\n\t\t\t\tDefaultFunc: schema.MultiEnvDefaultFunc([]string{\"ALICLOUD_OSS_ENDPOINT\", \"ALIBABA_CLOUD_OSS_ENDPOINT\", \"OSS_ENDPOINT\"}, \"\"),\n\t\t\t},\n\n\t\t\t\"bucket\": {\n\t\t\t\tType:        schema.TypeString,\n\t\t\t\tRequired:    true,\n\t\t\t\tDescription: \"The name of the OSS bucket\",\n\t\t\t},\n\n\t\t\t\"prefix\": {\n\t\t\t\tType:        schema.TypeString,\n\t\t\t\tOptional:    true,\n\t\t\t\tDescription: \"The directory where state files will be saved inside the bucket\",\n\t\t\t\tDefault:     \"env:\",\n\t\t\t\tValidateFunc: func(v interface{}, s string) ([]string, []error) {\n\t\t\t\t\tprefix := v.(string)\n\t\t\t\t\tif strings.HasPrefix(prefix, \"/\") || strings.HasPrefix(prefix, \"./\") {\n\t\t\t\t\t\treturn nil, []error{fmt.Errorf(\"workspace_key_prefix must not start with '/' or './'\")}\n\t\t\t\t\t}\n\t\t\t\t\treturn nil, nil\n\t\t\t\t},\n\t\t\t},\n\n\t\t\t\"key\": {\n\t\t\t\tType:        schema.TypeString,\n\t\t\t\tOptional:    true,\n\t\t\t\tDescription: \"The path of the state file inside the bucket\",\n\t\t\t\tValidateFunc: func(v interface{}, s string) ([]string, []error) {\n\t\t\t\t\tif strings.HasPrefix(v.(string), \"/\") || strings.HasSuffix(v.(string), \"/\") {\n\t\t\t\t\t\treturn nil, []error{fmt.Errorf(\"key can not start and end with '/'\")}\n\t\t\t\t\t}\n\t\t\t\t\treturn nil, nil\n\t\t\t\t},\n\t\t\t\tDefault: \"terraform.tfstate\",\n\t\t\t},\n\t\t\t\"tablestore_instance_name\": {","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/backend/remote-state/oss/backend.go#L143-L179","documentation":"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.","triggerScenarios":"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:'.","commonSituations":"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.","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'."],"exampleFix":"// before\nterraform {\n  backend \"oss\" {\n    prefix = \"/terraform/prod\"\n  }\n}\n// after\nterraform {\n  backend \"oss\" {\n    prefix = \"terraform/prod\"\n  }\n}","handlingStrategy":"validation","validationCode":"// Validate OSS backend prefix before Terraform init\nfunc validateOSSPrefix(prefix string) error {\n    if strings.HasPrefix(prefix, \"/\") || strings.HasPrefix(prefix, \"./\") {\n        return fmt.Errorf(\"prefix must not start with '/' or './'; use a flat key prefix like 'terraform/prod'\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["oss","validation","prefix","path"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}