googleapis/mcp-toolbox · error

failed to list instances: %w

Error message

failed to list instances: %w

What it means

Raised by ListInstances when s.InstanceAdmin.Instances fails against the Bigtable Admin API. Notably, if the error wraps bigtable.ErrPartiallyUnavailable (some instances in a cluster are temporarily unavailable), the source treats it as non-fatal and returns the partial list instead of this error. This error therefore indicates a total listing failure: auth, network, or project-level problems.

Source

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

	return map[string]string{"status": "instance updated successfully"}, nil
}

func (s *Source) DeleteInstance(ctx context.Context, instanceId string) (any, error) {
	err := s.InstanceAdmin.DeleteInstance(ctx, instanceId)
	if err != nil {
		return nil, fmt.Errorf("failed to delete instance: %w", err)
	}
	return map[string]string{"status": "instance deleted successfully"}, nil
}

func (s *Source) ListInstances(ctx context.Context) (any, error) {
	instances, err := s.InstanceAdmin.Instances(ctx)
	if err != nil {
		var partialErr bigtable.ErrPartiallyUnavailable
		if errors.As(err, &partialErr) {
			return instances, nil
		}
		return nil, fmt.Errorf("failed to list instances: %w", err)
	}
	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

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Check credentials: run `gcloud auth application-default login` or fix GOOGLE_APPLICATION_CREDENTIALS and confirm the service account has roles/bigtable.viewer or admin.
2. Verify the project ID passed to the Bigtable admin client matches the project containing the instances.
3. Retry with backoff on transient codes (Unavailable, Internal); check Google Cloud status dashboards for ongoing incidents.
4. Unwrap with errors.As to log the underlying gRPC status code for precise diagnosis.

// before calling ListInstances
if os.Getenv("GOOGLE_APPLICATION_CREDENTIALS") == "" && os.Getenv("BIGTABLE_PROJECT_ID") == "" {
    return errors.New("bigtable credentials/project not configured")
}

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

func isPermissionDenied(err error) bool {
    if st, ok := status.FromError(errors.Unwrap(err)); ok {
        return st.Code() == codes.PermissionDenied
    }
    return false
}

instances, err := src.ListInstances(ctx)
if err != nil {
    if isPermissionDenied(err) {
        return fmt.Errorf("check bigtable IAM roles for service account: %w", err)
    }
    // transient: retry with backoff
    return retryWithBackoff(func() error { _, err = src.ListInstances(ctx); return err })
}

When it happens

Trigger: Calling ListInstances(ctx) when the credentials lack bigtable.instances.list permission, the project ID is wrong or unset, quota/network issues break the admin RPC, or the API returns a non-partial failure not classified as ErrPartiallyUnavailable.

Common situations: Misconfigured Application Default Credentials (no GOOGLE_APPLICATION_CREDENTIALS or wrong service account); pointing at a project that doesn't exist or differs from where instances live; transient Google API outages beyond partial unavailability.

Related errors

• failed to delete instance: %w
• failed to get cluster: %w
• failed to list clusters: %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/3bc397611c7cc227. Report an issue: GitHub.