{"record":{"id":"90196a8408fec809","repo":"hashicorp/terraform","slug":"failed-to-retrieve-workspace-s-v-90196a","errorCode":null,"errorMessage":"Failed to retrieve workspace %s: %v","messagePattern":"Failed to retrieve workspace (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cloud/backend.go","lineNumber":740,"sourceCode":"}\n\n// StateMgr implements backend.Backend (which is embedded in backendrun.OperationsBackend).\nfunc (b *Cloud) StateMgr(name string) (statemgr.Full, tfdiags.Diagnostics) {\n\tvar diags tfdiags.Diagnostics\n\n\tvar remoteTFVersion string\n\n\tif name == backend.DefaultStateName {\n\t\treturn nil, diags.Append(backend.ErrDefaultWorkspaceNotSupported)\n\t}\n\n\tif b.WorkspaceMapping.Strategy() == WorkspaceNameStrategy && name != b.WorkspaceMapping.Name {\n\t\treturn nil, diags.Append(backend.ErrWorkspacesNotSupported)\n\t}\n\n\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\tif workspace != nil {\n\t\tremoteTFVersion = workspace.TerraformVersion\n\t}\n\n\tvar configuredProject *tfe.Project\n\n\t// Attempt to find project if configured\n\tif b.WorkspaceMapping.Project != \"\" {\n\t\tlistOpts := &tfe.ProjectListOptions{\n\t\t\tName: b.WorkspaceMapping.Project,\n\t\t}\n\t\tprojects, err := b.client.Projects.List(context.Background(), b.Organization, listOpts)\n\t\tif err != nil && err != tfe.ErrResourceNotFound {\n\t\t\t// This is a failure to make an API request, fail to initialize\n\t\t\treturn nil, diags.Append(fmt.Errorf(\"Attempted to find configured project %s but was unable to.\", b.WorkspaceMapping.Project))\n\t\t}\n\t\tfor _, p := range projects.Items {","sourceCodeStart":722,"sourceCodeEnd":758,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/cloud/backend.go#L722-L758","documentation":"Returned in backend StateMgr at backend.go:740 when b.client.Workspaces.Read returns any error other than tfe.ErrResourceNotFound while resolving the state manager for a workspace (i.e. during plan/apply). Note the capital 'F' (Failed) distinguishing it from 475. ErrResourceNotFound is allowed through so the backend can auto-create the workspace; all other errors are fatal to state setup.","triggerScenarios":"terraform plan/apply with a cloud backend; Workspaces.Read for the target workspace returns 401/403/500/rate-limit/network instead of 404.","commonSituations":"Token lacks read on the workspace; concurrent run locking API; TFE/HCP 5xx; proxy/rate-limit during a CI plan; workspace auto-create disabled and the workspace genuinely missing but surfaced as a permission error.","solutions":["Grant the token's team read access to the workspace (or the whole org).","Retry on transient 5xx/rate-limit; check status.cloud.hashicorp.com.","If workspace auto-create is disabled, create the workspace first in the UI."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Pre-flight workspace access before plan to surface auth issues early.\nif _, err := b.client.Workspaces.Read(ctx, org, name); err != nil && !errors.Is(err, tfe.ErrResourceNotFound) {\n    return fmt.Errorf(\"token cannot read workspace %s: %w\", name, err)\n}","typeGuard":"if errors.Is(err, tfe.ErrResourceNotFound) { /* allow auto-create path */ }","tryCatchPattern":"ws, err := b.client.Workspaces.Read(ctx, org, name)\nif err != nil && !errors.Is(err, tfe.ErrResourceNotFound) {\n    return nil, fmt.Errorf(\"Failed to retrieve workspace %s: %v\", name, err)\n}","preventionTips":["Grant workspace read to the token's team for plan/apply.","Retry transient 5xx/rate-limit errors; check the HCP status page."],"tags":["terraform","cloud-backend","tfe-api","workspaces","state"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T20:17:04.800Z"}