{"record":{"id":"e3b9318d334d40d0","repo":"hashicorp/terraform","slug":"workspace-s-not-found-the-configured-remote-ba","errorCode":null,"errorMessage":"workspace %s not found\n\nThe configured \"remote\" backend returns '404 Not Found' errors for resources\nthat do not exist, as well as for resources that a user doesn't have access\nto. If the resource does exist, please check the rights for the used token","messagePattern":"workspace (.+?) not found\n\nThe configured \"remote\" backend returns '404 Not Found' errors for resources\nthat do not exist, as well as for resources that a user doesn't have access\nto\\. If the resource does exist, please check the rights for the used token","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote/backend.go","lineNumber":741,"sourceCode":"\t\t// by this special case.\n\t\tDisableIntermediateSnapshots: client.runID != \"\",\n\t}, diags\n}\n\nfunc isLocalExecutionMode(execMode string) bool {\n\treturn execMode == \"local\"\n}\n\nfunc (b *Remote) fetchWorkspace(ctx context.Context, organization string, name string) (*tfe.Workspace, error) {\n\tremoteWorkspaceName := b.getRemoteWorkspaceName(name)\n\t// Retrieve the workspace for this operation.\n\tw, err := b.client.Workspaces.Read(ctx, b.organization, remoteWorkspaceName)\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\t\"The configured \\\"remote\\\" backend returns '404 Not Found' errors for resources\\n\"+\n\t\t\t\t\t\"that do not exist, as well as for resources that a user doesn't have access\\n\"+\n\t\t\t\t\t\"to. If the resource does exist, please check the rights for the used token\",\n\t\t\t\tname,\n\t\t\t)\n\t\tdefault:\n\t\t\terr := fmt.Errorf(\n\t\t\t\t\"the configured \\\"remote\\\" backend encountered an unexpected error:\\n\\n%s\",\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","sourceCodeStart":723,"sourceCodeEnd":759,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/backend/remote/backend.go#L723-L759","documentation":"Returned by fetchWorkspace() when Workspaces.Read fails with tfe.ErrResourceNotFound (HTTP 404). The message explicitly warns that the remote API returns 404 both for resources that do not exist AND for resources the token cannot access, so the real cause could be either a missing workspace or an authorization gap.","triggerScenarios":"Calling Operation() (plan/apply/refresh) which calls fetchWorkspace(); the resolved remote workspace name (after prefix logic in getRemoteWorkspaceName) does not exist in the org, or the token's team lacks read access to it (the API responds 404 instead of 403 to avoid leaking existence).","commonSituations":"Workspace name typo in the backend block; wrong `prefix` so the derived name is wrong; the workspace exists but belongs to a different org; the token's team was not granted access to that workspace; using a VCS-connected workspace name that differs from the configured one.","solutions":["Verify the exact workspace name: check getRemoteWorkspaceName() output — if a prefix is set the actual name is prefix+localName.","Confirm the token's team has at least read access to that specific workspace (Workspace Settings > Team Access).","Make sure `organization` in the backend block is correct and the workspace lives under it.","If the workspace genuinely does not exist, create it in the UI or via `terraform workspace new`."],"exampleFix":"// before - prefix produces wrong name, token lacks access\nbackend \"remote\" {\n  organization = \"acme\"\n  workspaces { prefix = \"myapp-\" }  // local \"default\" -> \"myapp-default\"\n}\n\n// after - fix the prefix OR grant the team read access to\n//         the workspace \"myapp-default\" in the UI","handlingStrategy":"validation","validationCode":"// Resolve the real remote name (mirrors getRemoteWorkspaceName) and precheck.\nfunc resolveName(local, prefix, exact string) string {\n    if local == \"default\" { return exact }\n    if prefix != \"\" && !strings.HasPrefix(local, prefix) { return prefix + local }\n    return local\n}","typeGuard":"func isAccessDenied404(err error) bool {\n    // 404 ambiguously means missing OR no-access; cannot distinguish client-side.\n    return errors.Is(err, tfe.ErrResourceNotFound)\n}","tryCatchPattern":"w, err := b.fetchWorkspace(ctx, org, name)\nif err != nil {\n    if errors.Is(err, context.Canceled) { return err }\n    // surface the helpful 'not found or no access' message to the user\n    return err\n}","preventionTips":["Double-check the prefix/exact-name mapping before running operations.","Grant the token's team explicit read access to each workspace used.","Confirm the workspace lives under the configured organization.","Pre-create workspaces to remove the missing-vs-forbidden ambiguity."],"tags":["workspace","authentication","tfe-api","operation"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}