Enum ScDataErrors 

pub enum ScDataErrors {
    Sparse(SparseErrors),
    Core(CoreErrors),
    InvalidArgument(String),
    BinaryIo(Error),
    NotRawCounts,
    HeaderEncodeFailed,
    HeaderDecodeFailed,
    FileVersionMismatch {
        expected: u32,
        found: u32,
    },
    ChunkBufferTooSmall {
        expected: usize,
        found: usize,
    },
    ChunkDecompressionFailed(u64),
    ChunkIndexNotFound(usize),
    ReaderModeMismatch {
        actual: &'static str,
        requested: &'static str,
    },
    ChunkPayloadTruncated {
        expected: usize,
        found: usize,
    },
    RawElemSizeInvalid(u8),
    V4ChunkCorrupt(String),
    V4MissingCellLibraryTable,
    ArchiveMagicMismatch,
    ArchiveVersionMismatch {
        expected: u32,
        found: u32,
    },
    ArchiveCorrupt(String),
    RawCountOverflow {
        value: u32,
        target_type: &'static str,
    },
    TargetSizeMismatch {
        header: f32,
        requested: f32,
    },
    FeatureTypeNotFound {
        requested: String,
        found: String,
    },
    H5UnexpectedStringType(String),
    Hdf5(Error),
    UnsupportH5ADFormat(String),
    DuplicateColumnName(String),
    UnsupportedH5Filter {
        dataset: String,
        filter_id: i32,
        filter_name: String,
    },
    H5ChunkDecode(String),
    ObsColumnMissing(String),
    LibSizeLengthMismatch {
        expected: usize,
        found: usize,
    },
    MtxHeaderInvalid(&'static str),
    MtxParseError {
        field: &'static str,
    },
    MtxUnsupported(String),
    MtxNotACount {
        value: String,
    },
    UnknownSparseFormat(String),
}

Error variants raised by bixverse-sc-data.

Grouped by subsystem.

Variants

Sparse(SparseErrors)

Propagates an error from bixverse-sparse.

Core(CoreErrors)

Propagates an error from bixverse-core.

InvalidArgument(String)

A caller-supplied argument is invalid.

BinaryIo(Error)

Wraps any std::io::Error encountered while reading or writing the bixverse binary sparse format.

Covers file creation, seeks, buffered writes, and raw reads against the memory-mapped region. Use #[from] conversion so ? works on any io::Result.

NotRawCounts

Error if counts do not seem to be raw counts during i/o

HeaderEncodeFailed

Bincode failed to encode the FileHeader or SparseDataHeader.

Practically unreachable for the fixed-layout headers used here, but kept as a non-panicking path so the writer never aborts a long ingest.

HeaderDecodeFailed

Bincode failed to decode the FileHeader or SparseDataHeader.

Indicates the file is truncated, corrupt, or was not produced by bixverse. The 64-byte fixed file header is the first thing read, so most “wrong file type” errors surface here.

FileVersionMismatch

File version does not match the current SC_FILE_VERSION.

Returned on read when an older or newer binary is opened. The fix is to regenerate the file with the current bixverse version.

Fields

expected: u32

Version the current build expects.

found: u32

Version actually read from the file header.

ChunkBufferTooSmall

A chunk buffer was shorter than the minimum header length.

Raised before any field is parsed from a decompressed chunk, so the reader can fail early instead of indexing out of bounds.

Fields

expected: usize

Minimum bytes required for the chunk header.

found: usize

Actual bytes available in the buffer.

ChunkDecompressionFailed(u64)

LZ4 decompression of a chunk failed.

The offset is reported to make corrupt regions locatable. Usually indicates file truncation or a mismatched compressed-size prefix.

ChunkIndexNotFound(usize)

A caller-supplied original index was not present in the file’s index map.

Indicates either a bug in the calling code (asking for an index that was never written) or a file that was generated with a different set of cells/genes than the caller assumes.

ReaderModeMismatch

A cell-based reader method was called on a gene-based file, or vice versa.

Replaces the previous runtime asserts. The two string fields describe the file’s actual layout and the layout the caller requested.

Fields

actual: &'static str

What the file is: “cell-based” or “gene-based”.

requested: &'static str

What the caller requested: “cell-based” or “gene-based”.

ChunkPayloadTruncated

A chunk’s declared payload lengths exceed the bytes actually present.

The three length fields in a chunk header are untrusted input. This is raised after they have been parsed but before any payload slice is taken, so a corrupt length cannot index out of bounds.

Fields

expected: usize

Total bytes the header’s length fields imply.

found: usize

Actual bytes available in the decompressed chunk.

RawElemSizeInvalid(u8)

The raw-count element-size discriminant was not recognised.

Valid values are RAW_ELEM_U16 (2), RAW_ELEM_U32 (4), and 0 for legacy files where the byte was zero padding. Anything else means the chunk is corrupt; reinterpreting it would misparse the whole payload.

V4ChunkCorrupt(String)

A v4 chunk is malformed: a bad codec byte, a bit width above 32, a body that ends before its own header says it should, or layers of unequal length handed to the encoder.

V4MissingCellLibraryTable

A v4 chunk drops its norm layer and recomputes it per entry, but the file carries no per-cell library-size table to recompute it from.

ArchiveMagicMismatch

The file is not a bixverse count archive.

ArchiveVersionMismatch

The archive was written by an incompatible archive format version.

Fields

expected: u32

Version the current build expects.

found: u32

Version actually read from the archive.

ArchiveCorrupt(String)

The archive is truncated or corrupt, or a chunk cannot be archived.

RawCountOverflow

A raw count read from disk does not fit the requested numeric type.

Raised by from_gene_chunks / from_cell_chunks instead of silently saturating. Pick a wider T (u32, f32, f64) for the affected dataset.

Fields

value: u32

The count that could not be represented.

target_type: &'static str

Name of the type it was being converted into.

TargetSizeMismatch

The target_size recorded in a file header disagrees with the one the caller requested.

Undoing a file’s own library-size normalisation requires the exact factor the writer used, so a mismatch always yields wrong numbers. Files written before target_size entered the header report 0.0 and are exempt from the check.

Fields

header: f32

Value stored in the file header.

requested: f32

Value the caller supplied.

FeatureTypeNotFound

Error for h5 ingestion if feature type is not found

Fields

requested: String

Requested feature type

found: String

Found feature types

H5UnexpectedStringType(String)

Error if the h5 string type cannot be read

Hdf5(Error)

Wraps any error from the hdf5 crate.

Covers file open failures, missing datasets (X/data, X/indices, X/indptr, obs/*), dtype mismatches, and slice reads. The wrapped error carries the original HDF5 message.

UnsupportH5ADFormat(String)

Provide custom error message for unsupported file formats.

DuplicateColumnName(String)

Two columns of an obs / var table end up with the same name after snake_case. DuckDB rejects the table, so the export stops before writing anything.

UnsupportedH5Filter

A dataset is compressed with a filter this build cannot decode.

Raised before the first read, because HDF5 itself reports the missing filter as a missing plugin directory: the path baked in at build time is a cargo OUT_DIR that no longer exists. Either re-save the file with compression="gzip", or build with the hdf5-filters feature, which adds LZF and Blosc.

Fields

dataset: String

Path of the dataset inside the file.

filter_id: i32

The HDF5 filter identifier.

filter_name: String

Human readable name for that identifier.

H5ChunkDecode(String)

A chunk read directly from an HDF5 file did not decode to the size its dataset says it should, or a read asked for elements past the end.

ObsColumnMissing(String)

A named obs column was requested but does not exist in the h5ad.

Primarily raised by write_h5_normalised_counts when the caller passes an obs_lib_size_col that isn’t in the file.

LibSizeLengthMismatch

The library-size vector read from obs does not match the number of cells in X.

Indicates a malformed h5ad — typical cause is a user-edited obs table whose row count drifted from the matrix.

Fields

expected: usize

Expected length (number of cells in X).

found: usize

Actual length of the obs column.

MtxHeaderInvalid(&'static str)

The header of an MTX file is malformed.

The static string describes which part of the header failed (shape line missing, wrong field count, unparseable counts). Comment lines starting with % are skipped before this fires.

MtxParseError

A field of the MTX shape line could not be parsed as a number.

field names the offending column (“cell count”, “gene count”, “entry count”) so that malformed inputs can be diagnosed without quoting user data. Which of the first two fields is which depends on the cells_as_rows orientation.

Fields

field: &'static str

Which field failed: “cell count”, “gene count”, or “entry count”.

MtxUnsupported(String)

The MTX banner names something the loader does not read: an object other than matrix, the dense array format, a complex field or a symmetry other than general.

MtxNotACount

An MTX value is not a raw count: negative, non-integral, not a number or beyond u32. The store holds raw counts, so a real file of normalised values cannot be loaded.

Fields

value: String

The offending value as written in the file.

UnknownSparseFormat(String)

The cs_type string did not match a known sparse format.

Accepted values are “csc” and “csr” (case-insensitive at the parser level). The unrecognised input is echoed back in the message.

Trait Implementations

impl Debug for ScDataErrors

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for ScDataErrors

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Error for ScDataErrors

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<CoreErrors> for ScDataErrors

fn from(source: CoreErrors) -> ScDataErrors

Converts to this type from the input type.

impl From<Error> for ScDataErrors

fn from(source: Error) -> ScDataErrors

Converts to this type from the input type.

impl From<Error> for ScDataErrors

fn from(source: Error) -> ScDataErrors

Converts to this type from the input type.

impl From<ScDataErrors> for ScErrors

fn from(source: ScDataErrors) -> ScErrors

Converts to this type from the input type.

impl From<SparseErrors> for ScDataErrors

fn from(source: SparseErrors) -> ScDataErrors

Converts to this type from the input type.