pub enum Error {
InvalidConfig(&'static str),
DimensionMismatch {
expected: usize,
actual: usize,
},
InvalidVector(&'static str),
DuplicateExternalId(u32),
CapacityExceeded(&'static str),
InvalidNode(u32),
InvalidLayer(u8),
InvalidMagic,
UnsupportedVersion {
expected: u16,
actual: u16,
},
CrcMismatch {
expected: u32,
actual: u32,
},
InvalidFile(&'static str),
Io(Error),
}Expand description
Recoverable failure from configuration, insert, search, or .hnsw I/O.
Match on the variant. The Display text is a diagnostic, not a stable
protocol.
Variants§
InvalidConfig(&'static str)
A crate::Config field failed validation, or a later setter received
an out-of-range value.
Returned by crate::HnswIndex::new, crate::HnswIndex::set_ef_search,
and crate::HnswIndex::set_level_mult. The payload names the failed
rule (dim, m, ef_construction, and ef_search must be greater
than zero; max_level must be in 1..=254; level_mult must be
finite and in [0, 1]). Fix the parameter and retry.
DimensionMismatch
A vector’s length does not match the expected dimension.
Insert and search compare against crate::Config::dim.
crate::vector::dot, crate::vector::cosine_distance, and
crate::vector::cosine_similarity compare the two argument lengths
(expected from the first slice, actual from the second). Supply a
slice of the expected length.
InvalidVector(&'static str)
A coordinate is non-finite, or the L2 norm is more than
crate::vector::UNIT_NORM_TOLERANCE from 1.
Returned only when crate::Config::check_vectors is set (or after
crate::HnswIndex::set_check_vectors /
crate::LoadedHnsw::set_check_vectors). Debug builds debug_assert
the same contract even when the flag is off. Normalize the vector and
drop NaN/Inf before retrying.
DuplicateExternalId(u32)
crate::HnswIndex::insert or crate::HnswIndex::build reused an
external ID already in the index.
The payload is the colliding ID. crate::HnswIndex::build assigns
0..n-1 and is for an empty index; a second build or build after
insert(0, …) fails here. Choose a free ID, or call insert to append.
CapacityExceeded(&'static str)
An in-memory or on-disk count cannot be stored in u32.
The graph may hold u32::MAX nodes (0..=u32::MAX - 1). A further
insert, a build ID that does not fit in u32, or a vector/edge table
that would overflow u32 returns this. The payload names the quantity.
The index is unchanged; split the data or use another index.
InvalidNode(u32)
A node index is missing from the graph, or is not a valid search entry.
Public crate::Graph accessors return empty/None instead of this
error. Insert and search can return it when the entry point is absent
or a mapped vector is missing. A failed crate::HnswIndex::insert is
rolled back, so the ID can be retried. Treat a persistent occurrence as
a corrupt in-memory graph or snapshot.
InvalidLayer(u8)
A layer is above a node’s assigned level, or the layer does not exist.
Public crate::Graph::edges returns an empty slice for this case.
Insert and search can return it when descent starts from an entry that
does not occupy the requested layer. Same recovery as
Error::InvalidNode.
InvalidMagic
The file does not start with crate::MAGIC.
The path is not a Bifrost .hnsw snapshot, or it is corrupt before the
magic. Open a file written by crate::HnswIndex::save.
UnsupportedVersion
The snapshot version is neither crate::VERSION nor
crate::MIGRATABLE_VERSION.
expected is the current writer version. actual is the file’s
version. Valid v2 files are rewritten to v3 on load; other versions
cannot be opened. Rebuild the index with this crate, or use a matching
reader.
CrcMismatch
The v3 data-section CRC32 does not match crate::Header::stored_crc.
expected is the header value; actual is the hash of bytes after
crate::HEADER_SIZE. The file was truncated or overwritten in place.
Restore a good snapshot; do not search this mapping.
InvalidFile(&'static str)
The snapshot failed layout or writer-invariant checks after a valid magic and version.
Typical causes: truncated sections, invalid header fields, duplicate
external IDs, gapped vector offsets, or unsorted edge lists. The
payload is a static reason. The file cannot be searched; rewrite it
from a live crate::HnswIndex.
Io(Error)
A filesystem or mmap error from save, load, or rename.
Implements std::error::Error::source. Retry transient I/O; check
permissions and disk space for persistent failures.
Trait Implementations§
Source§impl Error for Error
impl Error for Error
Source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
use the Display impl or to_string()