{"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/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/cloud/backend.go#L722-L758","documentation":"During StateMgr initialization, the backend reads the workspace from the TFE/HCP API. If the read fails with any error other than tfe.ErrResourceNotFound (which triggers workspace creation logic), the error is wrapped with this message and returned, preventing state manager initialization.","triggerScenarios":"Calling b.client.Workspaces.Read at backend.go:738 during StateMgr setup returns a non-nil, non-404 error. This happens during any Terraform operation (plan, apply, init) that needs a state manager for a cloud-backed workspace. The API call fails due to auth, permissions, rate limiting, or server errors.","commonSituations":"Running 'terraform plan' or 'terraform apply' against a cloud backend where the API token is expired or revoked. The token has insufficient permissions for the workspace. Transient network or server errors during state manager setup. Rate limiting from too many concurrent Terraform runs.","solutions":["Refresh the API token: run `terraform login <hostname>` or update TF_TOKEN_<hostname>.","Verify the token has read/create permissions for workspaces in the organization.","Retry after a brief wait if the error is transient.","Check that the workspace name or tags mapping resolves to a valid workspace."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Before StateMgr init, verify workspace accessibility\n_, err := b.client.Workspaces.Read(ctx, b.Organization, name)\nif err != nil && err != tfe.ErrResourceNotFound {\n    return fmt.Errorf(\"cannot access workspace %s: %w\", name, err)\n}","typeGuard":null,"tryCatchPattern":"// Retry workspace read during StateMgr init\nvar workspace *tfe.Workspace\nfor i := 0; i < 3; i++ {\n    workspace, err = b.client.Workspaces.Read(ctx, b.Organization, name)\n    if err == nil || err == tfe.ErrResourceNotFound {\n        break\n    }\n    if i == 2 {\n        return nil, diags.Append(fmt.Errorf(\"Failed to retrieve workspace %s: %v\", name, err))\n    }\n    time.Sleep(time.Duration(1<<i) * time.Second)\n}","preventionTips":["Run 'terraform login <hostname>' to ensure a valid token before plan/apply.","Verify the token has workspace read and create permissions.","Retry transient errors; HCP Terraform / TFE may rate-limit or have temporary outages.","Confirm the workspace name or tags strategy resolves to valid workspaces."],"tags":["terraform","cloud-backend","workspace","state-manager","tfe-api","go"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}