googleapis/mcp-toolbox · error

failed to create cluster: %w

Error message

failed to create cluster: %w

What it means

Raised by CreateCluster when the InstanceAdmin.CreateCluster admin RPC fails. The error wraps the original cause (PermissionDenied, InvalidArgument, FailedPrecondition, resource exhaustion). It means the new cluster (with the given zone and node count) could not be provisioned in the target instance.

Source

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

		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
}

func (s *Source) UpdateCluster(ctx context.Context, instanceId, clusterId string, serveNodes int32) (any, error) {
	err := s.InstanceAdmin.UpdateCluster(ctx, instanceId, clusterId, serveNodes)
	if err != nil {
		return nil, fmt.Errorf("failed to update cluster: %w", err)
	}
	return map[string]string{"status": "cluster updated successfully"}, nil
}

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

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Validate the zone against Bigtable-supported regions (`gcloud bigtable clusters create --help` or docs) and ensure the clusterId is unique in the instance.
2. Ensure numNodes >= 1 for PRODUCTION instances and check node quota in the Cloud Console.
3. Grant the caller roles/bigtable.admin so cluster creation is permitted.
4. Unwrap the error (errors.As / status.FromError) and map InvalidArgument/AlreadyExists/ResourceExhausted to input validation instead of retries.

Example fix

// before
conf := &bigtable.ClusterConfig{ClusterID: clusterId, Zone: zone, NumNodes: numNodes}
err := s.InstanceAdmin.CreateCluster(ctx, conf)
// after
if numNodes <= 0 {
    return nil, fmt.Errorf("numNodes must be >= 1 for production clusters")
}
conf := &bigtable.ClusterConfig{ClusterID: clusterId, Zone: "us-east1-b", NumNodes: numNodes}
err := s.InstanceAdmin.CreateCluster(ctx, conf)

var supportedZones = map[string]bool{"us-east1-b": true, "us-central1-c": true}

func validateClusterInput(instanceId, clusterId, zone string, numNodes int32, existing []string) error {
    if !supportedZones[zone] {
        return fmt.Errorf("unsupported zone %q", zone)
    }
    for _, id := range existing {
        if id == clusterId {
            return fmt.Errorf("cluster %q already exists", clusterId)
        }
    }
    if numNodes < 1 {
        return fmt.Errorf("numNodes must be >= 1")
    }
    return nil
}

func clusterCreateErrorCode(err error) codes.Code {
    if st, ok := status.FromError(errors.Unwrap(err)); ok {
        return st.Code()
    }
    return codes.Unknown
}
// AlreadyExists -> duplicate id; InvalidArgument -> bad zone/nodes; ResourceExhausted -> quota

err := createCluster(ctx, conf)
if err != nil {
    switch clusterCreateErrorCode(err) {
    case codes.AlreadyExists:
        return nil // treat create as idempotent
    case codes.ResourceExhausted:
        return fmt.Errorf("node quota exceeded; request quota increase")
    case codes.InvalidArgument:
        return fmt.Errorf("invalid zone or node count: %w", err)
    default:
        return fmt.Errorf("create cluster: %w", err)
    }
}

When it happens

Trigger: Calling CreateCluster(ctx, instanceId, clusterId, zone, numNodes) with an invalid/unsupported zone, a duplicate clusterId in the same instance, numNodes=0 for a production instance, insufficient quota for nodes, missing IAM permission, or the instance being in a state that rejects cluster creation.

Common situations: Typos in zone names (e.g. 'us-east1' instead of 'us-east1-b'); reusing a cluster ID that already exists; hitting project quota for Bigtable nodes; running with credentials lacking roles/bigtable.admin; attempting to add clusters to an instance type that disallows it.

Related errors

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

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