{"record":{"id":"deee8f203b1d0d6a","repo":"googleapis/mcp-toolbox","slug":"error-listing-alloydb-instances-w","errorCode":null,"errorMessage":"error listing AlloyDB instances: %w","messagePattern":"error listing AlloyDB instances: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sources/alloydbadmin/alloydbadmin.go","lineNumber":307,"sourceCode":"\n\tresp, err := service.Projects.Locations.Clusters.List(urlString).Do()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error listing AlloyDB clusters: %w\", err)\n\t}\n\treturn resp, nil\n}\n\nfunc (s *Source) ListInstance(ctx context.Context, project, location, cluster, accessToken string) (any, error) {\n\tservice, err := s.getService(ctx, accessToken)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\turlString := fmt.Sprintf(\"projects/%s/locations/%s/clusters/%s\", project, location, cluster)\n\n\tresp, err := service.Projects.Locations.Clusters.Instances.List(urlString).Do()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error listing AlloyDB instances: %w\", err)\n\t}\n\treturn resp, nil\n}\n\nfunc (s *Source) ListUsers(ctx context.Context, project, location, cluster, accessToken string) (any, error) {\n\tservice, err := s.getService(ctx, accessToken)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\turlString := fmt.Sprintf(\"projects/%s/locations/%s/clusters/%s\", project, location, cluster)\n\n\tresp, err := service.Projects.Locations.Clusters.Users.List(urlString).Do()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error listing AlloyDB users: %w\", err)\n\t}\n\treturn resp, nil\n}","sourceCodeStart":289,"sourceCodeEnd":325,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/alloydbadmin/alloydbadmin.go#L289-L325","documentation":"This error wraps a failure from the AlloyDB Admin API Instances.List call, which enumerates instances inside a cluster at path projects/*/locations/*/clusters/*. It is thrown when the REST list request fails with an HTTP error or transport problem. The wrapped error keeps the Google API details for diagnosis.","triggerScenarios":"Calling Source.ListInstance when the parent cluster does not exist (404), the cluster path is malformed, the token lacks scope, or the network call in Instances.List(urlString).Do() fails.","commonSituations":"Listing instances of a cluster that was deleted or lives in a different region, expired tokens, transient API outages, and rate-limiting under heavy polling.","solutions":["Verify the cluster exists (GetCluster) before listing its instances","Confirm project/location/cluster components are correct and complete","Refresh the access token and verify it has the alloydb scope","Retry transient 429/5xx errors with backoff","Unwrap with errors.As(*googleapi.Error) to branch on status codes"],"exampleFix":"// before\nresp, err := service.Projects.Locations.Clusters.Instances.List(urlString).Do()\nif err != nil { return nil, fmt.Errorf(\"error listing AlloyDB instances: %w\", err) }\n// after\nif _, err := s.GetCluster(ctx, project, location, cluster, accessToken); err != nil {\n    return nil, fmt.Errorf(\"cannot list instances, cluster %s unavailable: %w\", cluster, err)\n}\nresp, err := service.Projects.Locations.Clusters.Instances.List(urlString).Do()\nif err != nil {\n    return nil, fmt.Errorf(\"error listing AlloyDB instances: %w\", err)\n}","handlingStrategy":"try-catch","validationCode":"// Go: confirm the cluster exists before listing its instances\nif cluster == \"\" {\n    return fmt.Errorf(\"cluster is required\")\n}\nif _, err := s.GetCluster(ctx, project, location, cluster, accessToken); err != nil {\n    return fmt.Errorf(\"cluster %s not found: %w\", cluster, err)\n}","typeGuard":"func IsNotFound(err error) bool {\n    var gerr *googleapi.Error\n    return errors.As(err, &gerr) && gerr.Code == 404\n}","tryCatchPattern":"insts, err := s.ListInstance(ctx, project, location, cluster, accessToken)\nif err != nil {\n    var gerr *googleapi.Error\n    if errors.As(err, &gerr) && (gerr.Code == 429 || gerr.Code >= 500) {\n        return retryWithBackoff(...)\n    }\n    if errors.As(err, &gerr) && gerr.Code == 404 {\n        return nil, fmt.Errorf(\"cluster %q not found\", cluster)\n    }\n    return nil, err\n}","preventionTips":["Verify parent cluster existence before listing instances","Back off on rate limits when polling frequently","Keep tokens fresh for automated pollers","Cache cluster paths instead of reconstructing them ad hoc"],"tags":["gcp","alloydb","rest-api","authorization","network"],"backgroundTag":"gcp-api-request-failed","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}