Enum BlobCacheError 

pub enum BlobCacheError {
    Path(PathTokenError),
    Storage(StorageError),
    NoCloudHome,
    File(FileError),
    Commit(CommitNewFileError),
    Metadata(DbError),
    StorageSetup(StorageSetupError),
    OpeningAuthority(BlobOpeningAuthorityError),
    ExternalMissing {
        id: String,
        path: PathBuf,
        source: FileError,
    },
    ExternalSizeMismatch {
        id: String,
        path: PathBuf,
    },
    LocalSizeMismatch {
        path: PathBuf,
        expected_size: u64,
        actual_size: u64,
    },
    NoLocalCopy {
        namespace: String,
        id: String,
    },
    LocalityUnresolved {
        id: String,
    },
    NoExternalRef {
        id: String,
    },
    LocalIntegrity {
        path: PathBuf,
        expected_size: u64,
        actual_size: u64,
        expected_hash: ObjectHash,
        actual_hash: ObjectHash,
    },
    RangeOverflow {
        id: String,
        offset: u64,
        len: u64,
    },
    RangeOutOfBounds {
        id: String,
        offset: u64,
        end: u64,
        size: u64,
    },
}

Why a blob-cache operation failed.

Variants

Path(PathTokenError)

A blob id/namespace/cloud_path that can’t form a safe path — bad data that could escape the store dir or can’t be partitioned. The blob is refused before any path is built (the same gate the pull runs).

Storage(StorageError)

A cloud read failed: the blob isn’t in the cloud, or the backend errored (surfaced from the exact blob operations on CloudSyncObjectStorage).

NoCloudHome

A Remote blob’s bytes were needed from the cloud but no cloud home is connected, so there is no storage to fetch them from. A home-less store holds only Local blobs (external refs + the local store), which serve straight off disk and never reach the cloud-miss path; reaching here means a Remote blob was read with no provider connected — a real fault, surfaced rather than masked.

File(FileError)

A local-disk failure: a cache write, a folder move, or a test cache reset.

Commit(CommitNewFileError)

Publishing a staged cache file failed.

Metadata(DbError)

A blob-metadata query failed — resolving the blob’s locality, looking up its external ref, or reading its cache budget or expected size. A database read the blob path depends on, distinct from a disk I/O failure.

StorageSetup(StorageSetupError)

Building the sync storage from config failed — missing credentials or cloud configuration — when a Remote blob needed it. A configuration fault, not a disk I/O error.

OpeningAuthority(BlobOpeningAuthorityError)

The blob’s declared authority cannot open its stored representation.

ExternalMissing

A registered external blob ref (a user-provided Local blob’s user-owned file) points at a file that is no longer there — the user moved, renamed, or deleted it. Terminal: an external blob has no cloud copy to fall back to, so this never re-fetches. The host surfaces a “files missing / moved” state whose actions are relocate (pick the new folder, re-register) or re-import.

Fields

id: String

path: PathBuf

source: FileError

The underlying read failure — a missing file or a real I/O error, preserved rather than collapsed so the host sees why the read failed.

ExternalSizeMismatch

A registered external blob’s file is present but its length no longer matches the registered size — the user truncated it or replaced it with a different-length file. Terminal like Self::ExternalMissing: a mismatch means this is not the exact file coven registered.

Fields

id: String

path: PathBuf

LocalSizeMismatch

A local-store blob has a different length from its stored declaration.

Fields

path: PathBuf

expected_size: u64

actual_size: u64

NoLocalCopy

A Local blob (its gated locality root’s gate is off) has no copy in the local store. A Local blob has no cloud copy, so there is nothing to fall back to: the state is broken, not a cache miss. Surfaced loud rather than silently fetching from the cloud — a make_local rollback leftover, an interrupted materialize, or a lost local file would otherwise be papered over. The host re-materializes or repairs.

Fields

namespace: String

id: String

LocalityUnresolved

A blob could not be resolved to a locality: its namespace declares no blob-bearing table, or that table has no row with the id, or the row reaches no gated root or remote root — so the source of Local-vs-Remote truth can’t be read. In a consistent store every readable blob has a locality root, so this is a real fault — surfaced rather than guessing a source by probing.

Fields

id: String

NoExternalRef

The gate resolved a blob to Local + user-provided, but no external-ref row is registered for it. A user-provided Local blob’s bytes live only at the user’s path, tracked by that ref; its absence is corruption (a lost or never-written ref), not a cache miss to fall through — surfaced loud so the host repairs or re-imports.

Fields

id: String

LocalIntegrity

An authoritative local plaintext file exists at the exact path but its bytes differ from the row’s signed size/hash.

Fields

path: PathBuf

expected_size: u64

actual_size: u64

expected_hash: ObjectHash

actual_hash: ObjectHash

RangeOverflow

Adding the requested range length overflowed its offset.

Fields

id: String

offset: u64

len: u64

RangeOutOfBounds

The requested range lies outside the opened blob.

Fields

id: String

offset: u64

end: u64

size: u64

Trait Implementations

impl Debug for BlobCacheError

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

Formats the value using the given formatter.

impl Display for BlobCacheError

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

Formats the value using the given formatter.

impl Error for BlobCacheError

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<BlobCacheError> for StoreError

fn from(source: BlobCacheError) -> Self

Converts to this type from the input type.

impl From<CachedLocatorRemovalError> for BlobCacheError

fn from(error: CachedLocatorRemovalError) -> Self

Converts to this type from the input type.

impl From<DbError> for BlobCacheError

fn from(error: DbError) -> Self

Converts to this type from the input type.

impl From<LocalBlobStoreError> for BlobCacheError

fn from(e: LocalBlobStoreError) -> Self

Converts to this type from the input type.

impl From<PathTokenError> for BlobCacheError

fn from(e: PathTokenError) -> Self

Converts to this type from the input type.

impl From<RequiredLocalBlobPathError> for BlobCacheError

fn from(error: RequiredLocalBlobPathError) -> Self

Converts to this type from the input type.

impl From<StorageError> for BlobCacheError

fn from(e: StorageError) -> Self

Converts to this type from the input type.

impl From<StorageSetupError> for BlobCacheError

A Remote blob read needs sync storage; if building it from config fails (missing credentials or cloud configuration) the read surfaces that as a configuration fault, not a disk I/O error. The cache error preserves the setup failure’s message at this API boundary.

fn from(e: StorageSetupError) -> Self

Converts to this type from the input type.

impl From<StoreBlobFileError> for BlobCacheError

fn from(error: StoreBlobFileError) -> Self

Converts to this type from the input type.