Enum CacheError 

pub enum CacheError {
    NotFound {
        hash: Hash,
    },
    HashMismatch {
        expected: Hash,
        actual: Hash,
    },
    VerifyFailed {
        expected: Hash,
    },
    BlobTooLarge {
        hash: Hash,
        limit_bytes: u64,
    },
    NoOrigin {
        hash: Hash,
    },
    OriginError {
        hash: Hash,
        source: Error,
    },
    Store(Error),
    Feed(Error),
    Internal(Error),
    EvictionLimitExceeded {
        limit: usize,
    },
}

Errors surfaced by crate::CacheEngine.

A variant that wraps a cause names only itself in Display and returns the cause from std::error::Error::source. A .chain() walk therefore reaches every cause under a CacheError, such as a local disk fault that decdn_client::classify looks for, and a chain formatter ({:#} or {:?} on an anyhow::Error) names each cause once. Log a bare CacheError with CacheError::display_chain, not with plain Display.

Variants

NotFound

The requested blob was not found locally and the configured origin returned a not-found response.

Fields

hash: Hash

The hash that was requested.

HashMismatch

The origin returned bytes whose BLAKE3 hash did not match what was requested. The bytes are rejected and are not inserted into the store. A whole-stream failure: the assembled bytes hashed to actual, not the requested expected. A mid-stream bao chunk-group verify failure surfaces as Self::VerifyFailed instead, so actual here is always a real hash.

Fields

expected: Hash

The hash the caller asked for.

actual: Hash

The hash the origin’s bytes actually produced.

VerifyFailed

A teed bao verified-stream (#856, ADR 038) failed to decode against the content root: an interior chunk group did not verify — a corrupt or lying upstream. Distinct from Self::HashMismatch, which is a whole-stream hash mismatch; here the failure is at an interior group, so there is no meaningful whole-blob “actual” hash to report (#915). The bytes are rejected and are not inserted into the store.

Fields

expected: Hash

The hash the caller asked for (the content root the stream failed to verify against).

BlobTooLarge

The origin returned a blob larger than the configured max_blob_size_mb.

Fields

hash: Hash

The hash that was requested.

limit_bytes: u64

The configured ceiling, in bytes.

NoOrigin

The cache engine was asked to pull a miss but no origin was configured.

Fields

hash: Hash

The hash that was requested.

OriginError

The origin backend failed (network error, non-200 status, etc).

Fields

hash: Hash

The hash that was requested.

source: Error

Underlying error from the origin backend.

Store(Error)

This node’s own iroh-blobs store failed, or a store operation asked for bytes the store does not hold. Always a local fault: the bytes a sender feeds into an admit failing to arrive is Self::Feed, and bytes that fail to verify are Self::VerifyFailed.

Feed(Error)

The bao stream fed into an admit ended early or failed to read, or its claimed size cannot belong to the hash. A fault of the sender’s delivery, not of this node’s store.

Internal(Error)

A code bug in the cache: a broken internal invariant or a caught panic. Never an origin fault and never a store fault, so an operator reads it as a bug to report, not as a backend to check.

EvictionLimitExceeded

The local evicted-hash set is full. Hard cap on the number of distinct hashes the operator may evict in a single cache lifetime (issue #279) — protects the in-memory HashSet and the on-disk evicted.log from unbounded growth under e.g. an automation gone-wrong that mass-evicts on every request. Hitting this is well outside normal usage; the operator should investigate the caller before raising the cap.

Fields

limit: usize

The cap that was reached.

Implementations

impl CacheError

pub fn display_chain(&self) -> ErrorChain<'_>

Render this error and every cause under it on one line (store error: context: root cause). Use it wherever a bare CacheError reaches a log line or an operator-facing message.

pub fn origin_error_kind(&self) -> Option<&OriginError>

Walk the source chain of Self::OriginError looking for an OriginError. Returns Some when the failure originated in the HTTP origin’s encoding/decompression layer, even after anyhow::Context::with_context wrappers were stacked on top — anyhow::Error::chain() exposes every cause in the chain, and the typed variant we want lives at the root.

Tests assert on the typed variant via matches!; observability code can switch on the variant rather than parsing Display strings. Returns None for non-origin failures or origin failures that didn’t come from HttpOrigin’s decoder.

Trait Implementations

impl Debug for CacheError

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

Formats the value using the given formatter.

impl Display for CacheError

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

Formats the value using the given formatter.

impl Error for CacheError

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.