{"record":{"id":"99081519cd6f10f6","repo":"hashicorp/terraform","slug":"workspace-s-not-found-for-security-s-returns","errorCode":null,"errorMessage":"workspace %s not found\n\nFor security, %s returns '404 Not Found' responses for resources\nfor resources that a user doesn't have access to, in addition to resources that\ndo not exist. If the resource does exist, please check the permissions of the provided token.","messagePattern":"workspace (.+?) not found\n\nFor security, (.+?) returns '404 Not Found' responses for resources\nfor resources that a user doesn't have access to, in addition to resources that\ndo not exist\\. If the resource does exist, please check the permissions of the provided token\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cloud/backend.go","lineNumber":1336,"sourceCode":"\thostname         string\n\torganization     string\n\ttoken            string\n\tworkspaceMapping WorkspaceMapping\n}\n\nfunc isLocalExecutionMode(execMode string) bool {\n\treturn execMode == \"local\"\n}\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}","sourceCodeStart":1318,"sourceCodeEnd":1354,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/cloud/backend.go#L1318-L1354","documentation":"fetchWorkspace (backend.go:1336-1342) returns this when the go-tfe Workspaces.Read call fails with tfe.ErrResourceNotFound. The verbose message exists because HCP/TFE deliberately returns 404 both for non-existent resources and for resources the token lacks permission to see, so the error must disambiguate. This is the single most common workspace-access failure in the cloud backend.","triggerScenarios":"b.client.Workspaces.Read(ctx, organization, workspace) at backend.go:1330 returns an error that wraps/satisfies tfe.ErrResourceNotFound. Triggered by a wrong workspace name, wrong organization, or a token whose team has no access to that workspace.","commonSituations":"Typo in cloud block 'workspaces.name' or 'workspaces.tags' resolving to nothing. TF_WORKSPACE env var pointing at a non-existent workspace. Using an organization-scoped token in the wrong org. Token from a team that lacks 'Read' on the workspace. Recently renamed/deleted workspace.","solutions":["Verify the workspace name and organization in your cloud block / TF_WORKSPACE / TF_CLOUD_ORGANIZATION are spelled exactly as in the HCP/TFE UI.","Confirm the API token (TF_TOKEN_*, or `terraform login`) belongs to a team with at least Read access to that workspace.","Check the workspace wasn't renamed, deleted, or moved to another project/org.","For tag-based mapping, ensure at least one workspace actually carries the configured tags."],"exampleFix":"// before\ncloud { organization = \"myorg\" workspaces { name = \"app-prod\" } }\n// -> workspace app-prod not found ...\n// after: correct name (note dash vs underscore)\ncloud { organization = \"myorg\" workspaces { name = \"app_prod\" } }","handlingStrategy":"validation","validationCode":"// Pre-flight: confirm the workspace is readable with the current token.\nfunc workspaceExists(ctx context.Context, c *tfe.Client, org, ws string) bool {\n    _, err := c.Workspaces.Read(ctx, org, ws)\n    return err == nil\n}","typeGuard":null,"tryCatchPattern":"// Distinguish 404 from real-not-found vs permissions.\nif errors.Is(err, tfe.ErrResourceNotFound) {\n    // could be wrong name OR missing access; verify token team membership\n}","preventionTips":["Run a pre-flight Workspaces.Read in CI to fail fast with a clear message.","Keep workspace names and the cloud block in sync; lint configs.","Ensure the token's team has at least Read on every workspace referenced."],"tags":["terraform","tfe","workspace","permissions","authentication","cloud-backend"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}