{"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/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/cloud/backend.go#L645-L681","documentation":"During the Workspaces() listing operation, when a project name is configured in the workspace mapping, the backend queries the TFE/HCP API for projects matching that name. If the Projects.List call fails with any error other than tfe.ErrResourceNotFound (which is silently tolerated), the error is wrapped and returned. This prevents listing workspaces scoped to a project that cannot be resolved.","triggerScenarios":"Calling b.client.Projects.List at backend.go:661 returns a non-nil, non-404 error. This happens when the API request itself fails: authentication errors, rate limiting, server errors, network issues, or the API version does not support the projects endpoint.","commonSituations":"The API token has insufficient permissions to list projects. The TFE instance version does not support the Projects API. Rate limiting or transient server errors during a workspace listing operation. Network connectivity issues between Terraform CLI and the TFE/HCP host.","solutions":["Verify the project name is correct in your cloud workspaces block or TF_CLOUD_PROJECT env var.","Ensure the API token has permissions to read projects in the organization.","Retry the operation if the error is transient (rate limiting, server error).","If the TFE instance does not support projects, remove the project attribute from the workspaces block."],"exampleFix":"# before — project not supported or wrong name\ncloud {\n  workspaces {\n    project = \"nonexistent-or-unsupported\"\n  }\n}\n\n# after — remove project or use correct name\ncloud {\n  workspaces {\n    name = \"my-workspace\"\n  }\n}\n# Or with correct project:\ncloud {\n  workspaces {\n    tags = [\"env:prod\"]\n    project = \"correct-project-name\"\n  }\n}","handlingStrategy":"retry","validationCode":"// Before listing workspaces, verify project is accessible\nif b.WorkspaceMapping.Project != \"\" {\n    _, err := b.client.Projects.List(ctx, b.Organization, &tfe.ProjectListOptions{\n        Name: b.WorkspaceMapping.Project,\n    })\n    if err != nil && err != tfe.ErrResourceNotFound {\n        return fmt.Errorf(\"cannot access projects API: %w\", err)\n    }\n}","typeGuard":null,"tryCatchPattern":"// Retry project listing on transient errors\nfor i := 0; i < 3; i++ {\n    projects, err := b.client.Projects.List(ctx, b.Organization, listOpts)\n    if err == nil || err == tfe.ErrResourceNotFound {\n        break\n    }\n    if i == 2 {\n        return nil, diags.Append(fmt.Errorf(\"failed to retrieve project %s: %v\", listOpts.Name, err))\n    }\n    time.Sleep(time.Duration(1<<i) * time.Second)\n}","preventionTips":["Ensure the API token has project read permissions in the organization.","Verify the TFE/HCP Terraform instance supports the Projects API before using the project attribute.","Use 'terraform init' to validate cloud connectivity before running list operations.","Remove the project attribute if your TFE version does not support projects."],"tags":["terraform","cloud-backend","project","tfe-api","workspaces","go"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}