googleapis/mcp-toolbox · error

error listing AlloyDB instances: %w

Error message

error listing AlloyDB instances: %w

What it means

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.

Source

Thrown at internal/sources/alloydbadmin/alloydbadmin.go:307

	resp, err := service.Projects.Locations.Clusters.List(urlString).Do()
	if err != nil {
		return nil, fmt.Errorf("error listing AlloyDB clusters: %w", err)
	}
	return resp, nil
}

func (s *Source) ListInstance(ctx context.Context, project, location, cluster, accessToken string) (any, error) {
	service, err := s.getService(ctx, accessToken)
	if err != nil {
		return nil, err
	}

	urlString := fmt.Sprintf("projects/%s/locations/%s/clusters/%s", project, location, cluster)

	resp, err := service.Projects.Locations.Clusters.Instances.List(urlString).Do()
	if err != nil {
		return nil, fmt.Errorf("error listing AlloyDB instances: %w", err)
	}
	return resp, nil
}

func (s *Source) ListUsers(ctx context.Context, project, location, cluster, accessToken string) (any, error) {
	service, err := s.getService(ctx, accessToken)
	if err != nil {
		return nil, err
	}

	urlString := fmt.Sprintf("projects/%s/locations/%s/clusters/%s", project, location, cluster)

	resp, err := service.Projects.Locations.Clusters.Users.List(urlString).Do()
	if err != nil {
		return nil, fmt.Errorf("error listing AlloyDB users: %w", err)
	}
	return resp, nil
}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Verify the cluster exists (GetCluster) before listing its instances
2. Confirm project/location/cluster components are correct and complete
3. Refresh the access token and verify it has the alloydb scope
4. Retry transient 429/5xx errors with backoff
5. Unwrap with errors.As(*googleapi.Error) to branch on status codes

Example fix

// before
resp, err := service.Projects.Locations.Clusters.Instances.List(urlString).Do()
if err != nil { return nil, fmt.Errorf("error listing AlloyDB instances: %w", err) }
// after
if _, err := s.GetCluster(ctx, project, location, cluster, accessToken); err != nil {
    return nil, fmt.Errorf("cannot list instances, cluster %s unavailable: %w", cluster, err)
}
resp, err := service.Projects.Locations.Clusters.Instances.List(urlString).Do()
if err != nil {
    return nil, fmt.Errorf("error listing AlloyDB instances: %w", err)
}

// Go: confirm the cluster exists before listing its instances
if cluster == "" {
    return fmt.Errorf("cluster is required")
}
if _, err := s.GetCluster(ctx, project, location, cluster, accessToken); err != nil {
    return fmt.Errorf("cluster %s not found: %w", cluster, err)
}

func IsNotFound(err error) bool {
    var gerr *googleapi.Error
    return errors.As(err, &gerr) && gerr.Code == 404
}

insts, err := s.ListInstance(ctx, project, location, cluster, accessToken)
if err != nil {
    var gerr *googleapi.Error
    if errors.As(err, &gerr) && (gerr.Code == 429 || gerr.Code >= 500) {
        return retryWithBackoff(...)
    }
    if errors.As(err, &gerr) && gerr.Code == 404 {
        return nil, fmt.Errorf("cluster %q not found", cluster)
    }
    return nil, err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• error listing AlloyDB clusters: %w
• error listing AlloyDB users: %w
• error creating AlloyDB instance: %w
• error creating AlloyDB user: %w
• error getting AlloyDB cluster: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/deee8f203b1d0d6a. Report an issue: GitHub.