Enum Error 

pub enum Error {
    Io(Error),
    Serialization {
        message: String,
        source: Option<Box<dyn Error + Send + Sync>>,
    },
    Corruption(String),
    ColumnDecode {
        column: String,
        column_type: String,
        offset: usize,
        source: Box<Error>,
    },
    Schema(String),
    CqlParse(String),
    InvalidFormat(String),
    UnsupportedFormat(String),
    UnsupportedVersion {
        version: String,
        floor: String,
    },
    UnsupportedCommitLogVersion {
        version: i32,
        floor: i32,
        ceiling: i32,
    },
    CorruptCommitLogFrame(String),
    Timeout(String),
    QueryTimeout {
        operation: String,
        elapsed: Duration,
        limit: Duration,
    },
    InvalidPath(String),
    InvalidState(String),
    QueryExecution(String),
    ResultTooLarge {
        budget_bytes: usize,
        estimated_bytes: usize,
        rows: usize,
    },
    InvalidReadPath {
        value: String,
    },
    ForcedReadPathUnavailable {
        forced: &'static str,
        reason: String,
    },
    TypeConversion(String),
    Configuration(String),
    Storage(String),
    Memory(String),
    Concurrency(String),
    WriteDirLocked {
        path: String,
    },
    NotFound(String),
    Table(String),
    AlreadyExists(String),
    InvalidOperation(String),
    ConstraintViolation(String),
    Transaction(String),
    Index(String),
    Compaction(String),
    Internal(String),
    Parse(String),
    InvalidInput(String),
    UnsupportedQuery(String),
    Cancelled,
}

Main error type for CQLite operations

Variants

Io(Error)

I/O related errors

Serialization

Serialization/deserialization errors

Fields

message: String

source: Option<Box<dyn Error + Send + Sync>>

Corruption(String)

Data corruption errors

ColumnDecode

A SINGLE column’s value could not be decoded during row assembly (issue #3721).

Raised by the row decoder’s per-column loop (storage::sstable::reader::parsing::row_decoder::row_data) for BOTH the complex (non-frozen collection / multicell UDT) and the simple (scalar) column paths, wrapping the underlying decode failure as its source.

Why this is its OWN variant rather than a Corruption message

The row decoder used to answer a per-column decode failure with a bare break out of the column loop, so the row was assembled from the cells gathered SO FAR and returned as Ok: the failing column and every later on-disk column silently vanished and the SELECT reported success. A successful read with missing columns is indistinguishable from a row that legitimately has no value there, so nothing downstream can defend against it. Cassandra does not serve a short row either — a cell it cannot read raises out of UnfilteredSerializer and fails the read.

The block/partition row loops above the decoder deliberately treat an ordinary row-parse Err as end of the partition body (a well-formed SSTable’s last row is followed by a marker the loop detects by failing to parse another row). A per-column decode failure is NOT that condition, and the only way those loops can tell the two apart is by MATCHING on a dedicated variant — never by inspecting message text, which would be a heuristic (issue #28). Hence a variant and not a Corruption string.

Fields

column: String

Name of the column whose value could not be decoded.

column_type: String

The column type the decode was driven from: the AUTHORITATIVE on-disk SerializationHeader marshal type where the header carries one, else the supplied schema’s declared type (issue #1081/#28 — both are authoritative metadata, never guessed from bytes). Note this is the COLUMN’s type; for a collection, the failing ELEMENT or KEY type is named by source, which is why both are reported.

offset: usize

Byte offset, within the decompressed block buffer, of the failing column’s cell.

source: Box<Error>

The underlying decode failure.

Schema(String)

Schema validation errors

CqlParse(String)

CQL parsing errors

InvalidFormat(String)

Invalid format error (for SSTable parsing)

UnsupportedFormat(String)

Unsupported format error

UnsupportedVersion

SSTable version below the supported Cassandra 5.0 floor.

CQLite targets Cassandra 5.0 (na+/nb BIG, oa/da BTI). A pre-na (ma–me, Cassandra 3.x) BIG version, or a non-da BTI version, is out of scope and rejected at version-parse time.

Fields

version: String

floor: String

UnsupportedCommitLogVersion

Cassandra CommitLog segment descriptor version outside the supported Cassandra 5.0-era range (issue #2389).

The version is read authoritatively from the CommitLogDescriptor header, never inferred from the filename or file size (no-heuristics). A below/above-range version is rejected before the mutation stream is touched, mirroring BigVersionGates/BtiVersionGates.

Fields

version: i32

floor: i32

ceiling: i32

CorruptCommitLogFrame(String)

A Cassandra CommitLog per-record frame failed structural validation: a CRC mismatch (header or payload), an implausible record length, or a corrupt sync marker (issue #2389).

Distinct from a torn tail (clean truncation), which is reported to the caller as end-of-segment rather than as an error.

Timeout(String)

Timeout error

QueryTimeout

A query exceeded the configured query.max_execution_time budget (issue #1695).

Raised by the SINGLE timeout wrapper at the query-engine chokepoint (see crate::query::engine::deadline), never by an ad-hoc clock check inside a scan loop. Deliberately a variant of its own — distinct from Error::Timeout (an I/O-level timeout) and from every corruption variant — so an operator-imposed budget can never be mistaken for damaged data: it classifies as its own bounded telemetry category (crate::observability::ObsErrorCategory::Timeout).

Fields

operation: String

The bounded entry point that elapsed (e.g. query.execute).

elapsed: Duration

Time actually spent before the budget was abandoned.

limit: Duration

The configured budget (query.max_execution_time).

InvalidPath(String)

Invalid path error

InvalidState(String)

Invalid state error

QueryExecution(String)

Query execution errors

ResultTooLarge

A materialized result set exceeded the configured byte budget (issue #1582).

Raised by the SELECT executor while collecting a materialized result set, before it grows large enough to threaten the process’s <128MB memory target. This is the byte-unit successor to the coarse row-count safety valve: a byte ceiling correctly distinguishes 1M harmless skinny rows from 100k memory-blowing wide rows. The remedy is in the message — bound the result with a LIMIT clause, or consume it incrementally via the streaming query API instead of materializing the whole set.

Fields

budget_bytes: usize

Configured materialization byte budget that was exceeded.

estimated_bytes: usize

Estimated logical size (bytes) of the result collected so far.

rows: usize

Number of rows collected when the budget was exceeded.

InvalidReadPath

An unrecognized CQLITE_READ_PATH value was supplied (issue #1918).

Resolving the read-path forcing knob returns this distinct error rather than silently falling through to auto, so a typo’d knob is loud instead of a no-op. Names the invalid value and the allowed set.

Fields

value: String

The unrecognized value supplied to the knob.

ForcedReadPathUnavailable

Forced point read path could not run a partition-targeted lookup (issue #1918).

Raised whenever a forced read path cannot serve a query without silently diverging from the auto result. Under CQLITE_READ_PATH=point (or the equivalent QueryConfig field) this fires when the executor would not run a genuinely partition-targeted lookup — a classification fallback, an unwired targeted surface (e.g. a metadata IN fan-out), or a build/path that does not actually prune. Under CQLITE_READ_PATH=full it fires for a schema-less sole-pk point lookup, which only the specialized targeted seek can serve correctly (a full scan would return 0 rows instead of the row auto returns). Either way the query fails closed instead of silently returning a wrong result; reason names the concrete cause.

Fields

forced: &'static str

The forced mode that could not be satisfied ("point" or "full").

reason: String

The concrete fallback reason label (e.g. partition_key_not_fully_constrained).

TypeConversion(String)

Type conversion errors

Configuration(String)

Configuration errors

Storage(String)

Storage engine errors

Memory(String)

Memory management errors

Concurrency(String)

Lock/concurrency errors

WriteDirLocked

Write directory already locked by another process or Database instance

Returned by WriteEngine::new when the advisory lock on write_dir cannot be acquired because another WriteEngine (in this or another process) already holds it. Only one Database instance may hold a write_dir at a time.

Fields

path: String

The path that could not be locked

NotFound(String)

Resource not found

Table(String)

Table errors

AlreadyExists(String)

Resource already exists

InvalidOperation(String)

Invalid operation

ConstraintViolation(String)

Constraint violation

Transaction(String)

Transaction errors

Index(String)

Index errors

Compaction(String)

Compaction errors

Internal(String)

Generic internal error

Parse(String)

Parse error

InvalidInput(String)

Invalid input error

UnsupportedQuery(String)

Unsupported query error

Cancelled

The operation was cooperatively cancelled (issue #2264).

Raised by a long-running scan (e.g. the compaction streaming read) when its cancellation token is tripped — a client disconnect propagated from the Flight do_get path. Distinct from a genuine failure so callers can treat it as a clean, expected abort rather than corruption.

Implementations

impl Error

pub fn serialization(msg: impl Into<String>) -> Self

Create a serialization error

pub fn corruption(msg: impl Into<String>) -> Self

Create a corruption error

pub fn column_decode( column: impl Into<String>, column_type: impl Into<String>, offset: usize, source: Error, ) -> Self

Wrap a per-column decode failure with the column it belongs to (issue #3721).

pub fn schema(msg: impl Into<String>) -> Self

Create a schema error

pub fn cql_parse(msg: impl Into<String>) -> Self

Create a CQL parse error

pub fn invalid_format(msg: impl Into<String>) -> Self

Create an invalid format error

pub fn unsupported_format(msg: impl Into<String>) -> Self

Create an unsupported format error

pub fn invalid_path(msg: impl Into<String>) -> Self

Create an invalid path error

pub fn invalid_state(msg: impl Into<String>) -> Self

Create an invalid state error

pub fn query_execution(msg: impl Into<String>) -> Self

Create a query execution error

pub fn invalid_read_path(value: impl Into<String>) -> Self

Create an invalid-read-path error (issue #1918).

pub fn forced_read_path_unavailable( forced: &'static str, reason: impl Into<String>, ) -> Self

Create a forced-read-path-unavailable error (issue #1918). forced is the forced mode ("point" or "full"); reason is the concrete cause label.

pub fn type_conversion(msg: impl Into<String>) -> Self

Create a type conversion error

pub fn configuration(msg: impl Into<String>) -> Self

Create a configuration error

pub fn storage(msg: impl Into<String>) -> Self

Create a storage error

pub fn memory(msg: impl Into<String>) -> Self

Create a memory error

pub fn concurrency(msg: impl Into<String>) -> Self

Create a concurrency error

pub fn not_found(msg: impl Into<String>) -> Self

Create a not found error

pub fn already_exists(msg: impl Into<String>) -> Self

Create an already exists error

pub fn invalid_operation(msg: impl Into<String>) -> Self

Create an invalid operation error

pub fn constraint_violation(msg: impl Into<String>) -> Self

Create a constraint violation error

pub fn transaction(msg: impl Into<String>) -> Self

Create a transaction error

pub fn index(msg: impl Into<String>) -> Self

Create an index error

pub fn compaction(msg: impl Into<String>) -> Self

Create a compaction error

pub fn internal(msg: impl Into<String>) -> Self

Create an internal error

pub fn invalid_input(msg: impl Into<String>) -> Self

Create an invalid input error

pub fn parse(msg: impl Into<String>) -> Self

Create a parse error

pub fn unsupported_query(msg: impl Into<String>) -> Self

Create an unsupported query error

pub fn write_dir_locked(path: impl Into<String>) -> Self

Create a write-dir locked error

pub fn table_not_found(msg: impl Into<String>) -> Self

Create a table not found error

pub fn ambiguous_table(msg: impl Into<String>) -> Self

Create an ambiguous table error

pub fn is_recoverable(&self) -> bool

Check if this error is recoverable

pub fn category(&self) -> ErrorCategory

Get the error category

impl Error

pub fn obs_category(&self) -> ObsErrorCategory

Telemetry error category for this error (issue #1038).

Distinct from Error::category, which returns the developer-facing crate::error::ErrorCategory. This one returns the bounded, monitoring-oriented crate::observability::ObsErrorCategory.

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

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<Box<ErrorKind>> for Error

Convert from bincode errors

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<BtiError> for Error

fn from(err: BtiError) -> Self

Converts to this type from the input type.

impl<I> From<Err<Error<I>>> for Error

where I: Debug,

Convert from nom errors

fn from(err: Err<Error<I>>) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for Error

Convert from serde_json errors

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for CQLiteParseError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<ParserError> for Error

fn from(err: ParserError) -> Self

Converts to this type from the input type.