{"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/c9def3e214014c1188faabfc4a5bde5095139765/internal/backend/remote/backend.go#L669-L705","documentation":"Thrown by StateMgr() after Workspaces.Read returned ErrResourceNotFound and the subsequent Workspaces.Create() call also failed. The remote backend auto-creates a workspace when one doesn't exist, so this error means the creation step was rejected — most often a permissions or naming problem rather than a network issue.","triggerScenarios":"StateMgr() reaches the Create branch (workspace missing) and b.client.Workspaces.Create() returns an error: token lacks workspace-create permission, the derived name contains invalid characters, a name-collision race happened, or the organization hit its workspace quota.","commonSituations":"Using a read-only or member token instead of a team token with 'Create Workspaces' / admin rights; workspace name resolves to something with spaces, uppercase letters, or special chars due to a `prefix` mismatch; exceeding the org's plan workspace limit on HCP Terraform.","solutions":["Grant the API token's team permission to create workspaces (or admin access) in the org/team settings.","Pre-create the workspace manually in the HCP/TFE UI so StateMgr's Read succeeds and Create is never called.","Inspect the derived workspace name (prefix + local name) and ensure it uses only lowercase letters, digits, hyphens, underscores.","Check the wrapped %v for a quota/409/403 status and resolve accordingly (upgrade plan, pick a different name)."],"exampleFix":"// before - token without create rights triggers this on first run\n// after - pre-create the workspace, or grant the team\n//         'Create Workspaces' permission in HCP Terraform\n$ terraform workspace new prod   # OR create via UI:\n#   https://app.terraform.io/app/<org>/workspaces/new","handlingStrategy":"validation","validationCode":"// Pre-create the workspace so StateMgr's Create branch is never hit.\nfunc ensureWorkspace(ctx context.Context, c *tfe.Client, org, name string) error {\n    if _, err := c.Workspaces.Read(ctx, org, name); err == nil {\n        return nil\n    } else if !errors.Is(err, tfe.ErrResourceNotFound) {\n        return err\n    }\n    _, err := c.Workspaces.Create(ctx, org, tfe.WorkspaceCreateOptions{Name: tfe.String(name)})\n    return err\n}","typeGuard":"func isCreatePermitted(w *tfe.Workspace) bool {\n    return w != nil && w.Permissions != nil && w.Permissions.CanUpdate\n}","tryCatchPattern":"ws, err := b.client.Workspaces.Create(ctx, org, opts)\nif err != nil {\n    if errors.Is(err, context.Canceled) {\n        return err\n    }\n    return fmt.Errorf(\"Error creating workspace %s: %w\", name, err)\n}","preventionTips":["Grant the token's team 'Create Workspaces' permission, or pre-create workspaces in the UI/Terraform.","Keep workspace names lowercase, hyphen/underscore only to avoid invalid-name create failures.","Document required team permissions alongside the backend config.","Watch for workspace-quota limits on your HCP plan when relying on auto-create."],"tags":["workspace","permissions","tfe-api","state-mgr"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T20:17:04.800Z"}