Enum RetrievalError 

#[non_exhaustive]
pub enum RetrievalError {
    Hnsw(String),
    Bm25(String),
    Fusion(String),
    GraphTraversal(String),
    InvalidQuery(String),
    DimensionMismatch {
        expected: usize,
        actual: usize,
    },
    Configuration(String),
    EmbeddingStore(String),
    LinkStore(String),
    IndexNotInitialized(String),
    RebuildRequired {
        reason: String,
    },
    QueryTimeout {
        elapsed_ms: u64,
    },
    QueryCancelled,
    BudgetExceeded {
        current_usage: usize,
        item_size: usize,
        limit: usize,
    },
    Rerank(String),
}

Errors that can occur during retrieval operations.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Hnsw(String)

Vector index operation failed.

Bm25(String)

BM25 index operation failed.

Fusion(String)

Fusion operation failed.

GraphTraversal(String)

Graph traversal failed.

InvalidQuery(String)

Invalid query parameters.

DimensionMismatch

Dimension mismatch.

Fields

expected: usize

Expected dimensions.

actual: usize

Actual dimensions.

Configuration(String)

Configuration error.

EmbeddingStore(String)

Embedding store error.

LinkStore(String)

Link store error (for graph operations).

IndexNotInitialized(String)

Index not initialized.

RebuildRequired

Index rebuild required.

Fields

reason: String

Why rebuild is needed.

QueryTimeout

Query timed out before completing.

The search operation exceeded the configured timeout duration. This is a transient error: the query may succeed with a longer timeout or fewer results requested.

Fields

elapsed_ms: u64

Elapsed time in milliseconds before timeout.

QueryCancelled

Query was cancelled via cancellation token.

The search operation was cancelled before completing. This is a transient error: the query may succeed if not cancelled.

BudgetExceeded

Memory budget exceeded.

The insert operation would cause the index to exceed its configured memory budget. This is a permanent error: the same insert will always fail unless the budget is raised or existing data is removed.

Fields

current_usage: usize

Current estimated memory usage in bytes.

item_size: usize

Estimated size of the item being inserted in bytes.

limit: usize

Configured memory budget in bytes.

Rerank(String)

Reranking operation failed (permanent).

Implementations

impl RetrievalError

pub fn kind(&self) -> ErrorKind

Get the error classification (transient or permanent).

This classification determines retry behavior:

• Transient: May succeed on retry (network, external services)
• Permanent: Won’t be fixed by retry (validation, config, data)

Error Classification Table

Error Type	Classification	Reason
EmbeddingStore	Transient	External service, may recover
LinkStore	Transient	External service, may recover
Hnsw	Permanent	Index algorithm error
Bm25	Permanent	Index algorithm error
Fusion	Permanent	Score combination error
GraphTraversal	Permanent	Graph algorithm error
InvalidQuery	Permanent	User input validation
DimensionMismatch	Permanent	Data incompatibility
Configuration	Permanent	Setup/config issue
IndexNotInitialized	Permanent	Missing prerequisite
RebuildRequired	Permanent	Data integrity issue
QueryTimeout	Transient	May succeed with longer timeout
QueryCancelled	Transient	May succeed if not cancelled
BudgetExceeded	Permanent	Capacity limit, won’t auto-resolve

pub fn is_transient(&self) -> bool

Check if this error is transient (external/network/contention — may succeed on retry).

pub fn is_permanent(&self) -> bool

Check if this error is permanent (won’t be fixed by retry).

Permanent errors should be surfaced to the user immediately without retry attempts.

pub fn is_retryable(&self) -> bool

Check if this error is retryable (alias for is_transient).

Provided for backward compatibility and semantic clarity.

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

Create a rerank error (permanent).

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

Create an HNSW error (permanent).

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

Create a BM25 error (permanent).

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

Create a fusion error (permanent).

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

Create a graph traversal error (permanent).

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

Create an invalid query error (permanent).

pub fn dimension_mismatch(expected: usize, actual: usize) -> Self

Create a dimension mismatch error (permanent).

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

Create a configuration error (permanent).

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

Create an index not initialized error (permanent).

pub fn rebuild_required(reason: impl Into<String>) -> Self

Create a rebuild required error (permanent).

pub fn query_timeout(elapsed_ms: u64) -> Self

Create a query timeout error (transient).

pub fn query_cancelled() -> Self

Create a query cancelled error (transient).

pub fn budget_exceeded( current_usage: usize, item_size: usize, limit: usize, ) -> Self

Create a budget exceeded error (permanent).

Trait Implementations

impl Debug for RetrievalError

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

Formats the value using the given formatter.

impl Display for RetrievalError

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

Formats the value using the given formatter.

impl Error for RetrievalError

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.