{"record":{"id":"1d586be51b1c9e85","repo":"hashicorp/terraform","slug":"s-returned-an-unexpected-error-s","errorCode":null,"errorMessage":"%s returned an unexpected error:\n\n%s","messagePattern":"(.+?) returned an unexpected error:\n\n(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cloud/backend.go","lineNumber":1344,"sourceCode":"}\n\nfunc (b *Cloud) fetchWorkspace(ctx context.Context, organization string, workspace string) (*tfe.Workspace, error) {\n\t// Retrieve the workspace for this operation.\n\tw, err := b.client.Workspaces.Read(ctx, organization, workspace)\n\tif err != nil {\n\t\tswitch err {\n\t\tcase context.Canceled:\n\t\t\treturn nil, err\n\t\tcase tfe.ErrResourceNotFound:\n\t\t\treturn nil, fmt.Errorf(\n\t\t\t\t\"workspace %s not found\\n\\n\"+\n\t\t\t\t\tfmt.Sprintf(\"For security, %s returns '404 Not Found' responses for resources\\n\", b.appName)+\n\t\t\t\t\t\"for resources that a user doesn't have access to, in addition to resources that\\n\"+\n\t\t\t\t\t\"do not exist. If the resource does exist, please check the permissions of the provided token.\",\n\t\t\t\tworkspace,\n\t\t\t)\n\t\tdefault:\n\t\t\terr := fmt.Errorf(\n\t\t\t\t\"%s returned an unexpected error:\\n\\n%s\",\n\t\t\t\tb.appName,\n\t\t\t\terr,\n\t\t\t)\n\t\t\treturn nil, err\n\t\t}\n\t}\n\n\treturn w, nil\n}\n\n// validWorkspaceEnvVar ensures we have selected a valid workspace using TF_WORKSPACE:\n// First, it ensures the workspace specified by TF_WORKSPACE exists in the organization.\n// (This is because we deliberately DON'T implicitly create a workspace from TF_WORKSPACE,\n// unlike with a workspace specified via `name`.)\n// Second, if tags are specified in the configuration, it ensures TF_WORKSPACE belongs to the set\n// of available workspaces with those given tags.\nfunc (b *Cloud) validWorkspaceEnvVar(ctx context.Context, organization, workspace string) tfdiags.Diagnostic {","sourceCodeStart":1326,"sourceCodeEnd":1362,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/cloud/backend.go#L1326-L1362","documentation":"The default branch of fetchWorkspace (backend.go:1343-1349). Any Workspaces.Read error that is neither context.Canceled nor tfe.ErrResourceNotFound is wrapped here as an 'unexpected error' from HCP Terraform / TFE, including the raw error body. This is the catch-all for connectivity, auth (non-404), rate-limit, and server-failure responses.","triggerScenarios":"Workspaces.Read returns an error not matching context.Canceled or tfe.ErrResourceNotFound. Examples: 401 invalid token, 500/502 server error, TLS/DNS failure, 429 rate limit, request timeout.","commonSituations":"Expired or revoked API token (401). TFE maintenance window or outage. Custom hostname with a bad TLS certificate. DNS misconfiguration for the 'hostname' in the cloud block. Aggressive automation hitting rate limits.","solutions":["Read the embedded error body for the HTTP status code: re-login for 401, back off for 429, contact admin for 5xx.","Verify the 'hostname' in the cloud block and that the endpoint is reachable and has a valid certificate.","Re-authenticate with `terraform login` (or refresh TF_TOKEN_* / TFE_TOKEN).","Retry after a brief wait for transient server/network errors."],"exampleFix":"// before\ncloud { hostname = \"tfe.corp\" organization = \"myorg\" workspaces { name = \"app\" } }\n// -> tfe.corp returned an unexpected error: ... 401 Unauthorized\n// after: refresh credentials\nterraform login   # or export TF_TOKEN_app_at_tfe_corp=...","handlingStrategy":"try-catch","validationCode":"// Health-check the API endpoint and token before the real run.\nfunc apiHealthy(ctx context.Context, c *tfe.Client) bool {\n    _, err := c.Organizations.Read(ctx, \"my-org\")\n    return err == nil\n}","typeGuard":null,"tryCatchPattern":"// Classify the wrapped unexpected error.\nerr := b.fetchWorkspace(ctx, org, ws)\nvar apiErr *tfe.Error\nif errors.As(err, &apiErr) {\n    switch apiErr.Status {\n    case 401: refreshToken()\n    case 429: backoffRetry()\n    case 500,502,503: retryWithBackoff()\n    }\n}","preventionTips":["Validate the hostname and TLS cert in the cloud block.","Refresh tokens before they expire; use `terraform login`.","Add a connectivity pre-check in CI before running plan/apply."],"tags":["terraform","tfe","api","network","authentication","cloud-backend"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}