{"record":{"id":"2389f49dc30957f8","repo":"hashicorp/terraform","slug":"failed-to-retrieve-workspace-s-v","errorCode":null,"errorMessage":"Failed to retrieve workspace %s: %v","messagePattern":"Failed to retrieve workspace (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote/backend.go","lineNumber":671,"sourceCode":"\tvar diags tfdiags.Diagnostics\n\tif b.workspace == \"\" && name == backend.DefaultStateName {\n\t\treturn nil, diags.Append(backend.ErrDefaultWorkspaceNotSupported)\n\t}\n\tif b.prefix == \"\" && name != backend.DefaultStateName {\n\t\treturn nil, diags.Append(backend.ErrWorkspacesNotSupported)\n\t}\n\n\t// Configure the remote workspace name.\n\tswitch {\n\tcase name == backend.DefaultStateName:\n\t\tname = b.workspace\n\tcase b.prefix != \"\" && !strings.HasPrefix(name, b.prefix):\n\t\tname = b.prefix + name\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\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}","sourceCodeStart":653,"sourceCodeEnd":689,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/backend/remote/backend.go#L653-L689","documentation":"Thrown when Workspaces.Read fails with any error OTHER than tfe.ErrResourceNotFound while resolving a workspace for state operations. The NotFound branch is handled separately (it triggers auto-create), so this error represents a genuine read failure: network, auth, permission, or server error.","triggerScenarios":"b.client.Workspaces.Read(ctx, org, name) returns a non-nil, non-NotFound error. Typical causes: 401/403 (token not authorized for the workspace), 5xx from TFE, request timeout, DNS/connectivity failure, or rate limiting.","commonSituations":"Token lacks 'Read Workspace' permission on the target workspace; transient TFE outage or maintenance window; corporate proxy intercepting the connection; rate-limited by TFC; expired token mid-session.","solutions":["Check the wrapped error (%v) for HTTP status: 401/403 means re-login or broaden token scope, 5xx/timeout means retry.","Confirm the API token's team has 'Read' access to the workspace.","Retry 'terraform init'/'plan' after confirming TFC/TFE status is green.","If behind a proxy, verify HTTPS_PROXY and TLS inspection settings."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Before operations, sanity-check workspace readability with explicit error handling.\nfunc workspaceReadable(ctx context.Context, client *tfe.Client, org, name string) error {\n    _, err := client.Workspaces.Read(ctx, org, name)\n    if err != nil && !errors.Is(err, tfe.ErrResourceNotFound) {\n        return fmt.Errorf(\"workspace %s read check failed: %w\", name, err)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"// Distinguish NotFound (handled by auto-create) from real failures.\nif _, err := b.client.Workspaces.Read(ctx, org, name); err != nil {\n    if errors.Is(err, tfe.ErrResourceNotFound) { /* create path */ }\n    if errors.Is(err, context.Canceled) { return err }\n    // transient (5xx/429/timeout) -> retry with backoff; auth (401/403) -> re-login","preventionTips":["Pre-create workspaces in CI rather than relying on auto-create, so read failures are clearly auth/network.","Grant the token's team at least 'Read' on all target workspaces.","Run operations through retry-with-backoff for transient transport errors."],"tags":["backend","remote-backend","workspace","api-error","network","permissions","go"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}