Error handling

Updated Sep 01, 2026

Builder validation returns ChutoroError::InvalidMinClusterSize when the provided minimum cluster size is zero. Chutoro::run surfaces runtime failures via ChutoroError variants:

  • EmptySource: returned when a DataSource yields zero items.
  • InsufficientItems: triggered if len() falls below min_cluster_size.
  • BackendUnavailable: emitted when the requested ExecutionStrategy is not compiled into the binary.
  • DataSource: raised when distance or distance_batch fails. Use ChutoroError::data_source_code() to recover the underlying DataSourceErrorCode and respond programmatically.
  • CpuHnswFailure, CpuMstFailure, and CpuHierarchyFailure: raised when the CPU backend encounters internal failures in HNSW construction/search, MST construction, or hierarchy extraction.

Callers using extract_labels_from_mst can inspect its typed HierarchyError result for invalid input and internal reference failures: EmptyDataset, MinClusterSizeTooLarge, InvalidEdgeWeight, and InvalidEdgeEndpoint describe invalid extraction inputs, while InvalidForestReference, InvalidClusterReference, and InvalidPointReference identify inconsistent intermediate hierarchy state. Each variant exposes a stable machine-readable code through code() and the code's as_str() method.

DataSourceError distinguishes out-of-bounds indices, dimension mismatches, and invalid buffers. Propagate these errors verbatim, so callers receive stable error codes via DataSourceError::code().