Enum PersistError 

#[non_exhaustive]
pub enum PersistError {
    Io {
        path: PathBuf,
        source: Error,
    },
    BadMagic {
        found: [u8; 8],
    },
    UnsupportedVersion {
        found: u32,
        supported: u32,
    },
    ChecksumMismatch {
        expected: u32,
        computed: u32,
    },
    TruncatedHeader {
        needed: usize,
        found: usize,
    },
    TruncatedPayload {
        needed: u64,
        found: u64,
    },
    InvalidMetric {
        tag: u8,
    },
    UnsupportedMetric {
        metric: DistanceMetric,
    },
    InvalidIndexType {
        found: String,
        expected: &'static str,
    },
    InvalidPayload {
        reason: &'static str,
    },
    Compression {
        reason: &'static str,
    },
    IndexBuild(IqdbError),
    Unsupported {
        feature: &'static str,
        available_in: &'static str,
    },
}

An error from an iqdb-persist save, load, or format operation.

Each variant identifies one specific failure. The enum is #[non_exhaustive]: future releases may add variants without it being a breaking change, so a match on it must include a wildcard arm.

Examples

use iqdb_persist::PersistError;

let err = PersistError::ChecksumMismatch { expected: 0xDEADBEEF, computed: 0x00000000 };
assert!(err.to_string().contains("checksum mismatch"));

let unsup = PersistError::Unsupported { feature: "compression", available_in: "v0.4" };
assert!(unsup.to_string().contains("v0.4"));

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.

Io

An OS-level I/O failure occurred while reading or writing a snapshot file. path is the file whose operation failed; source is the underlying std::io::Error and is reachable via std::error::Error::source.

Fields

path: PathBuf

The path whose I/O operation failed.

source: Error

The underlying I/O error.

BadMagic

The first eight bytes of the file did not match crate::MAGIC — the file is not an iqdb snapshot.

Fields

found: [u8; 8]

The eight magic bytes actually read from the file.

UnsupportedVersion

The header’s format-version field is not one this build supports. found is what the file declared; supported is the version this build writes.

Fields

found: u32

The version the file declared.

supported: u32

The format version this build supports.

ChecksumMismatch

The CRC32 of the payload bytes did not match the header’s stored value — the payload is corrupted or has been tampered with.

Fields

expected: u32

The CRC32 the header claimed.

computed: u32

The CRC32 actually computed over the payload bytes.

TruncatedHeader

The file ended before the full header could be read. needed is the number of bytes the parser still wanted; found is how many were available.

Fields

needed: usize

Bytes the parser still needed.

found: usize

Bytes that were available.

TruncatedPayload

The file ended before the full payload could be read.

Fields

needed: u64

Payload bytes the parser still needed.

found: u64

Payload bytes that were available.

InvalidMetric

The header’s metric tag does not correspond to any iqdb_types::DistanceMetric variant this build knows about.

Fields

tag: u8

The on-disk metric tag byte.

UnsupportedMetric

A DistanceMetric this build has no on-disk tag for. Only occurs on save if a newer iqdb-types introduced a metric variant that this build of iqdb-persist predates — DistanceMetric is #[non_exhaustive].

Fields

metric: DistanceMetric

The metric that could not be encoded.

InvalidIndexType

The header’s index-type tag does not match the concrete I’s crate::Persistable::INDEX_TYPE.

Fields

found: String

The index-type tag the file declared.

expected: &'static str

The index-type tag the caller’s I requires.

InvalidPayload

The payload bytes decoded successfully at the byte level but produced a structurally invalid index.

Fields

reason: &'static str

Short, stable identifier for the structural check that failed.

Compression

A compression or decompression step failed: an invalid codec parameter on save, or a codec error / length mismatch on load. (Bulk on-disk corruption is caught earlier by the payload CRC32 and surfaces as ChecksumMismatch.)

Fields

reason: &'static str

Short, stable identifier for the codec failure.

IndexBuild(IqdbError)

A nested IqdbError surfaced from a downstream construction step — typically iqdb_index::Index::new or iqdb_index::IndexCore::insert called from inside a crate::Persistable::load_from impl.

Unsupported

A configuration value asked for a feature that this build does not implement yet.

Fields

feature: &'static str

Short, stable identifier for the unsupported feature.

available_in: &'static str

The version where the feature lands.

Trait Implementations

impl Debug for PersistError

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

Formats the value using the given formatter.

impl Display for PersistError

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

Formats the value using the given formatter.

impl Error for PersistError

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 ForgeError for PersistError

fn kind(&self) -> &'static str

Returns the kind of error, typically matching the enum variant

fn caption(&self) -> &'static str

Returns a human-readable caption for the error

fn is_retryable(&self) -> bool

Returns true if the operation can be retried

fn is_fatal(&self) -> bool

Returns true if the error is fatal and should terminate the program

fn status_code(&self) -> u16

Returns an appropriate HTTP status code for the error

fn exit_code(&self) -> i32

Returns an appropriate process exit code for the error

fn user_message(&self) -> String

Returns a user-facing message that can be shown to end users

fn dev_message(&self) -> String

Returns a detailed technical message for developers/logs

fn backtrace(&self) -> Option<&Backtrace>

Returns a backtrace if available

fn register(&self)

Registers the error with the central error registry

impl From<IqdbError> for PersistError

fn from(value: IqdbError) -> Self

Converts to this type from the input type.