googleapis/mcp-toolbox · error

failed to list clusters: %w

Error message

failed to list clusters: %w

What it means

Raised by ListClusters when the InstanceAdmin.Clusters RPC for the given instance fails outright. Like ListInstances, partial availability (bigtable.ErrPartiallyUnavailable) is swallowed and the partial cluster list is returned; this error signals a complete failure such as a bad instance ID, missing permissions, or transport problems.

Source

Thrown at internal/sources/bigtable/admin_wrappers.go:96

	return instances, nil
}

func (s *Source) GetCluster(ctx context.Context, instanceId, clusterId string) (any, error) {
	cluster, err := s.InstanceAdmin.GetCluster(ctx, instanceId, clusterId)
	if err != nil {
		return nil, fmt.Errorf("failed to get cluster: %w", err)
	}
	return cluster, nil
}

func (s *Source) ListClusters(ctx context.Context, instanceId string) (any, error) {
	clusters, err := s.InstanceAdmin.Clusters(ctx, instanceId)
	if err != nil {
		var partialErr bigtable.ErrPartiallyUnavailable
		if errors.As(err, &partialErr) {
			return clusters, nil
		}
		return nil, fmt.Errorf("failed to list clusters: %w", err)
	}
	return clusters, nil
}

func (s *Source) CreateCluster(ctx context.Context, instanceId, clusterId, zone string, numNodes int32) (any, error) {
	conf := &bigtable.ClusterConfig{
		InstanceID: instanceId,
		ClusterID:  clusterId,
		Zone:       zone,
		NumNodes:   numNodes,
	}
	err := s.InstanceAdmin.CreateCluster(ctx, conf)
	if err != nil {
		return nil, fmt.Errorf("failed to create cluster: %w", err)
	}
	return map[string]string{"status": "cluster created successfully"}, nil
}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Verify the instanceId with ListInstances or `gcloud bigtable instances describe`.
2. Fix IAM: grant roles/bigtable.reader or roles/bigtable.admin to the caller's service account.
3. Confirm the admin client targets the correct project.
4. Retry with exponential backoff only for transient gRPC codes (Unavailable, DeadlineExceeded); log the unwrapped status code otherwise.

// before calling ListClusters
instances, err := src.ListInstances(ctx)
if err != nil {
    return fmt.Errorf("cannot verify instance %q: %w", instanceId, err)
}
// confirm instanceId exists among instances before listing its clusters

func isPartialUnavailable(err error) bool {
    var pe bigtable.ErrPartiallyUnavailable
    return errors.As(err, &pe)
}

clusters, err := src.ListClusters(ctx, instanceId)
if err != nil {
    if isGRPCCode(err, codes.NotFound) {
        return fmt.Errorf("instance %q not found", instanceId)
    }
    // fall back to one retry before surfacing
    if clusters, err = retryOnce(ctx, src.ListClusters, instanceId); err != nil {
        return err
    }
}

When it happens

Trigger: Calling ListClusters(ctx, instanceId) with a nonexistent or misspelled instanceId (NotFound), lacking bigtable.clusters.list permission, wrong project, or non-partial transient failures of the admin API.

Common situations: Passing an instance name instead of its ID; the instance was deleted between calls; service account missing Bigtable roles after credential rotation; brief Google API disruption causing full (not partial) RPC failure.

Related errors

• failed to delete instance: %w
• failed to list instances: %w
• failed to get cluster: %w
• failed to create cluster: %w
• failed to update cluster: %w

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