{"record":{"id":"8ff3b63f4a56244b","repo":"hashicorp/terraform","slug":"failed-to-retrieve-project-s-v","errorCode":null,"errorMessage":"failed to retrieve project %s: %v","messagePattern":"failed to retrieve project (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cloud/backend.go","lineNumber":663,"sourceCode":"\t\t// The backend will end up applying both filters but that should always\n\t\t// be the same result set anyway.\n\t\tfor _, tag := range options.TagBindings {\n\t\t\tif options.Tags != \"\" {\n\t\t\t\toptions.Tags = options.Tags + \",\"\n\t\t\t}\n\t\t\toptions.Tags = options.Tags + tag.Key\n\t\t}\n\n\t}\n\tlog.Printf(\"[TRACE] cloud: Listing workspaces with tag bindings %q\", b.WorkspaceMapping.DescribeTags())\n\n\tif b.WorkspaceMapping.Project != \"\" {\n\t\tlistOpts := &tfe.ProjectListOptions{\n\t\t\tName: b.WorkspaceMapping.Project,\n\t\t}\n\t\tprojects, err := b.client.Projects.List(context.Background(), b.Organization, listOpts)\n\t\tif err != nil && err != tfe.ErrResourceNotFound {\n\t\t\treturn nil, diags.Append(fmt.Errorf(\"failed to retrieve project %s: %v\", listOpts.Name, err))\n\t\t}\n\t\tfor _, p := range projects.Items {\n\t\t\tif p.Name == b.WorkspaceMapping.Project {\n\t\t\t\toptions.ProjectID = p.ID\n\t\t\t\tbreak\n\t\t\t}\n\t\t}\n\t}\n\n\tfor {\n\t\twl, err := b.client.Workspaces.List(context.Background(), b.Organization, options)\n\t\tif err != nil {\n\t\t\treturn nil, diags.Append(err)\n\t\t}\n\n\t\tfor _, w := range wl.Items {\n\t\t\tnames = append(names, w.Name)\n\t\t}","sourceCodeStart":645,"sourceCodeEnd":681,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/cloud/backend.go#L645-L681","documentation":"Returned in backend Workspaces() (workspace listing, e.g. terraform workspace list) at backend.go:663 when b.client.Projects.List returns an error that is NOT tfe.ErrResourceNotFound while resolving the configured project name. The %s is the project name and %v the raw TFE API error. ErrResourceNotFound is intentionally swallowed (project just filters to nothing).","triggerScenarios":"A cloud backend with project = \"X\" (or TF_CLOUD_PROJECT=X); terraform workspace list triggers project lookup; the Projects.List API call fails with a non-404 error (401/403/500/rate-limit/network).","commonSituations":"Token lacks permission to read projects; TFE/HCP API outage or 5xx; rate limiting; transient network error hitting the API.","solutions":["Confirm the token's team has project-read permission in the organization.","Retry on transient API errors or rate limits (the TFE client retries automatically; if still failing, back off).","Verify TF_CLOUD_PROJECT / project name spelling and that the API host is healthy."],"exampleFix":"// before: token cannot list projects\ncloud { organization = \"acme\" workspaces { name = \"dev\" project = \"platform\" } }\n\n// after: grant project read or remove project scoping\ncloud { organization = \"acme\" workspaces { name = \"dev\" } }","handlingStrategy":"try-catch","validationCode":"// Confirm project-read permission before listing workspaces.\nif _, err := b.client.Projects.List(ctx, b.Organization, &tfe.ProjectListOptions{Name: project}); err != nil && !errors.Is(err, tfe.ErrResourceNotFound) {\n    return fmt.Errorf(\"cannot read projects: %w; check token permissions\", err)\n}","typeGuard":"if errors.Is(err, tfe.ErrResourceNotFound) { /* tolerate */ } else { /* report */ }","tryCatchPattern":"// Distinguish tolerated 404 from real errors.\nprojects, err := b.client.Projects.List(ctx, org, opts)\nif errors.Is(err, tfe.ErrResourceNotFound) {\n    projects = nil // proceed with empty filter\n} else if err != nil {\n    return fmt.Errorf(\"failed to retrieve project %s: %v\", project, err)\n}","preventionTips":["Grant the token's team project-read permission.","Retry on transient API errors; check HCP/TFE status."],"tags":["terraform","cloud-backend","tfe-api","projects","permissions"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}