{"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/c9def3e214014c1188faabfc4a5bde5095139765/internal/backend/remote/backend.go#L653-L689","documentation":"Thrown by StateMgr() when b.client.Workspaces.Read() returns an error that is NOT tfe.ErrResourceNotFound. It means the call to read the workspace from HCP Terraform / Terraform Enterprise failed outright — this is a catch-all for authentication, network, rate-limit, and server-side failures, distinct from the 'workspace missing' case which is handled separately and triggers auto-create.","triggerScenarios":"Calling StateMgr() (e.g. `terraform init`, `terraform plan`, any state operation) when Workspaces.Read fails with anything other than 404: a 401/403 (bad/expired token, org access denied), 429 rate limit, 5xx server error, DNS/TLS failure, or an invalid organization name.","commonSituations":"API token expired or revoked; organization name misspelled in the backend block; the token belongs to a team without read access to the org; transient TFE/HCP outage; corporate proxy intercepting the TLS connection to app.terraform.io; hostname misconfigured for a self-hosted TFE install.","solutions":["Verify the API token is valid and not expired: re-run `terraform login` or regenerate the token in the HCP/TFE UI.","Confirm the backend block's `organization` exactly matches the org name in the UI (case-sensitive).","Check that the token's team has at least read access to the organization and the workspace.","If transient, retry the command; for repeated failures inspect the wrapped %v error for the HTTP status (401/403/429/500).","For self-hosted TFE, confirm the `hostname` value and that the host's TLS certificate is trusted by the CLI."],"exampleFix":"// before - expired/missing token\nbackend \"remote\" {\n  hostname     = \"app.terraform.io\"\n  organization = \"acme\"\n  workspaces { name = \"prod\" }\n}\n\n// after - refresh credentials via `terraform login`,\n// or set a fresh token in ~/.terraformrc / credentials helper\n$ terraform login app.terraform.io","handlingStrategy":"validation","validationCode":"// Validate backend config + token reachability before any state op.\nfunc checkWorkspaceReadable(ctx context.Context, c *tfe.Client, org, name string) error {\n    _, err := c.Workspaces.Read(ctx, org, name)\n    if err != nil && err != tfe.ErrResourceNotFound {\n        return fmt.Errorf(\"workspace read precheck failed for %s/%s: %w\", org, name, err)\n    }\n    return nil\n}","typeGuard":"func isNotFound(err error) bool {\n    return errors.Is(err, tfe.ErrResourceNotFound)\n}","tryCatchPattern":"ws, err := b.client.Workspaces.Read(ctx, org, name)\nif err != nil {\n    if errors.Is(err, tfe.ErrResourceNotFound) {\n        // not found -> handle create path\n    } else if errors.Is(err, context.Canceled) {\n        return err\n    }\n    return fmt.Errorf(\"Failed to retrieve workspace %s: %w\", name, err)\n}","preventionTips":["Store the API token via `terraform login` or a credentials helper so it is fresh and not hard-coded.","Pin and review the `organization` and workspace name/prefix in the backend block in code review.","Run `terraform init` after any backend config change to fail fast on auth/org errors.","Use a least-privilege team token with documented required scopes (read workspaces + state)."],"tags":["workspace","tfe-api","authentication","network","state-mgr"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}