{"record":{"id":"64a7c2ef8b3d2189","repo":"hashicorp/terraform","slug":"error-creating-workspace-s-v-64a7c2","errorCode":null,"errorMessage":"error creating workspace %s: %v","messagePattern":"error creating workspace (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cloud/backend.go","lineNumber":810,"sourceCode":"\t\t\t\tcreateOpts := tfe.ProjectCreateOptions{\n\t\t\t\t\tName: b.WorkspaceMapping.Project,\n\t\t\t\t}\n\t\t\t\t// didn't find project, create it instead\n\t\t\t\tlog.Printf(\"[TRACE] cloud: Creating %s project %s/%s\", b.appName, b.Organization, b.WorkspaceMapping.Project)\n\t\t\t\tproject, err := b.client.Projects.Create(context.Background(), b.Organization, createOpts)\n\t\t\t\tif err != nil && err != tfe.ErrResourceNotFound {\n\t\t\t\t\treturn nil, diags.Append(fmt.Errorf(\"failed to create project %s: %v\", b.WorkspaceMapping.Project, err))\n\t\t\t\t}\n\t\t\t\tconfiguredProject = project\n\t\t\t\tworkspaceCreateOptions.Project = configuredProject\n\t\t\t}\n\t\t}\n\n\t\t// Create a workspace\n\t\tlog.Printf(\"[TRACE] cloud: Creating %s workspace %s/%s\", b.appName, b.Organization, name)\n\t\tworkspace, err = b.client.Workspaces.Create(context.Background(), b.Organization, workspaceCreateOptions)\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\n\t\tremoteTFVersion = workspace.TerraformVersion\n\n\t\t// Attempt to set the new workspace to use this version of Terraform. This\n\t\t// can fail if there's no enabled tool_version whose name matches our\n\t\t// version string, but that's expected sometimes -- just warn and continue.\n\t\tversionOptions := tfe.WorkspaceUpdateOptions{\n\t\t\tTerraformVersion: tfe.String(tfversion.String()),\n\t\t}\n\t\t_, err := b.client.Workspaces.UpdateByID(context.Background(), workspace.ID, versionOptions)\n\t\tif err == nil {\n\t\t\tremoteTFVersion = tfversion.String()\n\t\t} else {\n\t\t\t// TODO: Ideally we could rely on the client to tell us what the actual\n\t\t\t// problem was, but we currently can't get enough context from the error\n\t\t\t// object to do a nicely formatted message, so we're just assuming the\n\t\t\t// issue was that the version wasn't available since that's probably what","sourceCodeStart":792,"sourceCodeEnd":828,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/cloud/backend.go#L792-L828","documentation":"Returned in backend StateMgr at backend.go:810 when b.client.Workspaces.Create fails during workspace auto-creation for a cloud backend (the workspace does not exist and must be created before plan/apply can proceed). %s=workspace name, %v=the raw TFE API error.","triggerScenarios":"terraform plan/apply with a cloud backend whose workspace name does not yet exist; Workspaces.Create returns an error (permission, 409 conflict, validation, 5xx, rate limit).","commonSituations":"Token lacks workspace-create permission; workspace name already exists but in a different project (conflict); invalid workspace name characters; org workspace limit reached; execution-mode or other create option rejected by API.","solutions":["Pre-create the workspace in the HCP/TFE UI and let Terraform select it.","Grant the token's team workspace-create (admin) permission on the org/project.","Resolve 409 conflicts (rename or pick an unused workspace name).","Check the workspace name for invalid characters and org quota limits."],"exampleFix":"// before: workspace missing, token cannot create\ncloud { organization = \"acme\" workspaces { name = \"prod-app\" } }\n\n// after: pre-create workspace in UI, or grant admin token\ncloud { organization = \"acme\" workspaces { name = \"prod-app\" } }\n# create workspace 'prod-app' in HCP Terraform UI first, or use an admin token","handlingStrategy":"try-catch","validationCode":"// Pre-create the workspace (idempotent) before plan/apply.\nfunc ensureWorkspace(c *tfe.Client, org, name string) error {\n    if _, err := c.Workspaces.Create(ctx, org, tfe.WorkspaceCreateOptions{Name: name}); err != nil {\n        if !isConflict(err) { return err }\n    }\n    return nil\n}","typeGuard":"if isConflict(err) { /* workspace already exists; read it instead */ }","tryCatchPattern":"ws, err := b.client.Workspaces.Create(ctx, org, opts)\nif err != nil {\n    if isConflict(err) {\n        ws, err = b.client.Workspaces.Read(ctx, org, name)\n    }\n    if err != nil {\n        return nil, fmt.Errorf(\"error creating workspace %s: %v\", name, err)\n    }\n}","preventionTips":["Pre-create workspaces in the HCP/TFE UI when auto-create is risky.","Grant workspace-create (admin) permission to the token's team.","Validate workspace name characters and check org quota limits."],"tags":["terraform","cloud-backend","tfe-api","workspaces","create","permissions"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}