googleapis/mcp-toolbox · error

error listing AlloyDB instances

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.

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
• error listing AlloyDB users
• error creating AlloyDB instance
• error creating AlloyDB user
• error getting AlloyDB cluster

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

Appendix: 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)