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,
    },
    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

Internal(String)

An internal write-queue plumbing failure not attributable to a specific storage capability: the writer task’s channel closed (the task panicked or was dropped) or its oneshot reply was dropped before sending a result.

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.