{"record":{"id":"2964c35e6603feee","repo":"hashicorp/terraform","slug":"error-creating-workspace-s-v","errorCode":null,"errorMessage":"Error creating workspace %s: %v","messagePattern":"Error creating workspace (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote/backend.go","lineNumber":687,"sourceCode":"\tworkspace, err := b.client.Workspaces.Read(context.Background(), b.organization, name)\n\tif err != nil && err != tfe.ErrResourceNotFound {\n\t\treturn nil, diags.Append(fmt.Errorf(\"Failed to retrieve workspace %s: %v\", name, err))\n\t}\n\n\tif err == tfe.ErrResourceNotFound {\n\t\toptions := tfe.WorkspaceCreateOptions{\n\t\t\tName: tfe.String(name),\n\t\t}\n\n\t\t// We only set the Terraform Version for the new workspace if this is\n\t\t// a release candidate or a final release.\n\t\tif tfversion.Prerelease == \"\" || strings.HasPrefix(tfversion.Prerelease, \"rc\") {\n\t\t\toptions.TerraformVersion = tfe.String(tfversion.String())\n\t\t}\n\n\t\tworkspace, err = b.client.Workspaces.Create(context.Background(), b.organization, options)\n\t\tif err != nil {\n\t\t\treturn nil, diags.Append(fmt.Errorf(\"Error creating workspace %s: %v\", name, err))\n\t\t}\n\t}\n\n\t// This is a fallback error check. Most code paths should use other\n\t// mechanisms to check the version, then set the ignoreVersionConflict\n\t// field to true. This check is only in place to ensure that we don't\n\t// accidentally upgrade state with a new code path, and the version check\n\t// logic is coarser and simpler.\n\tif !b.ignoreVersionConflict {\n\t\twsv := workspace.TerraformVersion\n\t\t// Explicitly ignore the pseudo-version \"latest\" here, as it will cause\n\t\t// plan and apply to always fail.\n\t\tif wsv != tfversion.String() && wsv != \"latest\" {\n\t\t\treturn nil, diags.Append(fmt.Errorf(\"Remote workspace Terraform version %q does not match local Terraform version %q\", workspace.TerraformVersion, tfversion.String()))\n\t\t}\n\t}\n\n\tclient := &remoteClient{","sourceCodeStart":669,"sourceCodeEnd":705,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/backend/remote/backend.go#L669-L705","documentation":"Thrown after Workspaces.Read returned NotFound and the backend attempted to auto-create the workspace via Workspaces.Create. The create call failed. This path only runs when the workspace does not yet exist and the backend is permitted to auto-provision it.","triggerScenarios":"b.client.Workspaces.Create(ctx, org, options) returns an error. Common: token/team lacks 'Create Workspace' permission on the org; workspace name fails validation (invalid characters, too long); org workspace quota exceeded; name collides with a soft-deleted workspace.","commonSituations":"Using a read-only service token in CI; workspace name with uppercase letters or spaces (TFC requires lowercase, URL-safe); exceeding the org's workspace limit; TFE project with restricted workspace creation.","solutions":["Inspect the wrapped error (%v) for the precise API rejection reason.","Grant the token's team 'Admin' or 'Create Workspaces' permission on the organization, or pre-create the workspace in the UI.","Fix the workspace name to be lowercase, alphanumeric, with only '-' or '_' separators.","If a quota is hit, free up a workspace slot or request a quota increase, then retry 'terraform init'."],"exampleFix":"// before: name derived from user input with spaces\nname = \"My Workspace\"\n// after: normalize the workspace name\nname = strings.ToLower(strings.ReplaceAll(\"My Workspace\", \" \", \"-\"))","handlingStrategy":"validation","validationCode":"// Validate workspace name rules (TFC: lowercase, URL-safe) before relying on auto-create.\nvar wsNameRe = regexp.MustCompile(`^[a-z0-9][a-z0-9-_]{0,90}$`)\nfunc validWorkspaceName(name string) bool { return wsNameRe.MatchString(name) }","typeGuard":null,"tryCatchPattern":"// On create failure, branch on the wrapped status.\nif _, err := b.client.Workspaces.Create(ctx, org, opts); err != nil {\n    if isStatus(err, 403) { /* grant Create permission */ }\n    if isStatus(err, 409) { /* name conflict / soft-deleted */ }\n}","preventionTips":["Pre-provision workspaces via Terraform/tfe provider so the runtime token only needs read/apply.","Normalize workspace names to lowercase kebab-case at the source.","Ensure the token's team has 'Create Workspaces' permission before relying on auto-create in CI."],"tags":["backend","remote-backend","workspace","create","permissions","validation","go"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}