Enum StorageError 

pub enum StorageError {
    NotFound {
        capability: StorageCapability,
        resource: &'static str,
        key: String,
    },
    AlreadyExists {
        capability: StorageCapability,
        resource: &'static str,
        key: String,
    },
    Conflict {
        capability: StorageCapability,
        operation: Cow<'static, str>,
        message: String,
    },
    InvalidInput {
        capability: StorageCapability,
        operation: Cow<'static, str>,
        message: String,
    },
    Unsupported {
        capability: StorageCapability,
        operation: Cow<'static, str>,
        message: String,
    },
    Pool {
        operation: Cow<'static, str>,
        message: String,
    },
    Timeout {
        operation: Cow<'static, str>,
    },
    Transaction {
        operation: Cow<'static, str>,
        message: String,
    },
    Serialization {
        capability: StorageCapability,
        message: String,
    },
    IndexMaintenance {
        capability: StorageCapability,
        message: String,
    },
    Driver {
        capability: StorageCapability,
        operation: Cow<'static, str>,
        source: Box<dyn StdError + Send + Sync>,
    },
    WriteQueueFull {
        timeout_ms: u64,
    },
    WriterTaskTerminated {
        request_state: WriterTaskRequestState,
    },
    Internal(String),
    WriterTaskNoRuntime,
    CapacityFloor {
        capability: StorageCapability,
        volume: String,
        available_bytes: u64,
        floor_bytes: u64,
    },
}

Unified error type for all storage operations.

Variants

NotFound

Fields

capability: StorageCapability

resource: &'static str

key: String

AlreadyExists

Fields

capability: StorageCapability

resource: &'static str

key: String

Conflict

Fields

capability: StorageCapability

operation: Cow<'static, str>

message: String

InvalidInput

Fields

capability: StorageCapability

operation: Cow<'static, str>

message: String

Unsupported

Fields

capability: StorageCapability

operation: Cow<'static, str>

message: String

Pool

Fields

operation: Cow<'static, str>

message: String

Timeout

Fields

operation: Cow<'static, str>

Transaction

Fields

operation: Cow<'static, str>

message: String

Serialization

Fields

capability: StorageCapability

message: String

IndexMaintenance

Fields

capability: StorageCapability

message: String

Driver

Fields

capability: StorageCapability

operation: Cow<'static, str>

source: Box<dyn StdError + Send + Sync>

WriteQueueFull

The bounded write-queue channel (ADR-067 Component A) did not free capacity within the caller-supplied deadline. Returned only when a caller wraps WriterTaskHandle::send’s channel.send().await in a tokio::time::timeout; there is no immediate-error try_send path.

Fields

timeout_ms: u64

WriterTaskTerminated

The pool’s single writer task has terminated permanently. The state identifies what is known about this request at that boundary. Retrying on the same pool cannot recover the closed writer task.

Fields

request_state: WriterTaskRequestState

Internal(String)

An internal storage failure not attributable to a specific storage capability.

WriterTaskNoRuntime

KHIVE_WRITE_QUEUE=1 is set but the calling thread has no Tokio runtime context, so the writer task cannot be spawned (ADR-067 Component A). Returned instead of panicking. See crates/khive-storage/docs/api/error-taxonomy.md#writertasknoruntime.

CapacityFloor

A filesystem-backed capability (e.g. BlobStore) refused a write because volume’s available space, after accounting for the pending write, would drop below the configured free-space floor (khive#292).

Fields

capability: StorageCapability

volume: String

available_bytes: u64

floor_bytes: u64

Implementations

impl StorageError

pub fn driver( capability: StorageCapability, operation: impl Into<Cow<'static, str>>, source: impl StdError + Send + Sync + 'static, ) -> Self

Construct a Driver error wrapping a backend-specific error source.

pub fn capability(&self) -> Option<StorageCapability>

Return the storage capability surface that produced this error, if any.

pub fn is_retryable(&self) -> bool

Whether this error is transient and the operation may succeed on retry.

pub fn is_fts5_syntax_error(&self) -> bool

Whether this error is an FTS5 query-parser rejection of the MATCH expression itself, as opposed to a connection/pool/driver-level failure of the text-search backend.

True only for Driver errors from the Text capability at the fts_search operation whose message names one of SQLite’s FTS5 parser failure modes (syntax error, stack overflow, unsupported column/phrase/NEAR query); all other errors return false.

Callers that fail-open the FTS leg of a hybrid search (degrading to vector-only results on a bad query string) MUST gate on this predicate rather than on StorageError broadly — treating every Err as degradable turns a real backend outage into a silently-empty “successful” search (issue #389). See crates/khive-storage/docs/api/error-taxonomy.md#is_fts5_syntax_error.

pub fn is_unique_constraint_violation(&self) -> bool

Whether this error is a UNIQUE constraint violation from a raw SQL execute (e.g. an INSERT racing an existing row under a natural key). True only for Driver errors from the Sql capability whose operation is one of execute, pool_writer.execute, or tx.execute, and whose message contains UNIQUE constraint failed. Batch/script operations are intentionally excluded.

Callers that treat exact-key duplicates as a tolerated no-op (ADR-081 §4 serve-ledger idempotency) MUST gate on this predicate rather than swallowing every Driver error at execute — that would also hide genuine write failures (disk full, corruption). See crates/khive-storage/docs/api/error-taxonomy.md#is_unique_constraint_violation.

Trait Implementations

impl Debug for StorageError

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

Formats the value using the given formatter.

impl Display for StorageError

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

Formats the value using the given formatter.

impl Error for StorageError

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.