Enum StorageError 

pub enum StorageError {
    Corrupted(String),
    DatabaseNotFound(PathBuf),
    DatabaseLocked,
    Transaction(String),
    Serialization(String),
    Redb(String),
    SchemaVersionMismatch {
        expected: u32,
        found: u32,
    },
    TableNotFound(String),
    SubstrateUpgradeRequired {
        found: u8,
        current: u8,
    },
    SubstrateFormatTooNew {
        found: u8,
        current: u8,
    },
    SubstrateMigrationTooLarge {
        store_size: u64,
        projected_peak: u64,
        budget: u64,
    },
    SubstrateMigrationInsufficientDisk {
        store_size: u64,
        required: u64,
        available: u64,
    },
    SubstrateMigrationRequiresSync,
}

Storage-related errors.

These errors indicate problems with the underlying storage layer.

Variants

Corrupted(String)

Database file or data is corrupted.

DatabaseNotFound(PathBuf)

Database file not found at expected path.

DatabaseLocked

Database is locked by another process.

Transaction(String)

Transaction failed (commit, rollback, etc.).

Serialization(String)

Serialization/deserialization error.

Redb(String)

Error from the redb storage engine.

SchemaVersionMismatch

Database schema version doesn’t match expected version.

Fields

expected: u32

Expected schema version.

found: u32

Actual schema version found in database.

TableNotFound(String)

Table not found in database.

SubstrateUpgradeRequired

The database was written by an older substrate format and must be migrated before it can be opened.

The substrate format is the storage-substrate axis (redb file format + value serializer), distinct from the logical schema_version. This is the typed, actionable signal a guided migration keys off — it must never be a raw redb UpgradeRequired or a bincode decode panic leaking through.

A writable open of such a store migrates automatically (the migration gate is wired in a later work item); this error is surfaced only when migration cannot proceed (e.g. a read-only open).

Fields

found: u8

Substrate format found in the database (0 = pre-4.0 / bincode era).

current: u8

Current substrate format this build writes and reads.

SubstrateFormatTooNew

The database was written by a newer PulseDB whose substrate format is ahead of this build — a forward-incompatibility.

This build must not touch the file: doing so risks silent corruption. Upgrade PulseDB to a version that understands substrate format found.

Fields

found: u8

Substrate format found in the database.

current: u8

Current substrate format this build supports.

SubstrateMigrationTooLarge

The bincode→postcard codec migration cannot run as a single transaction because the store is larger than the safe single-txn ceiling, and no declared available-memory budget (or a too-small one) authorizes it.

This is the fail-closed-above-floor valve (VS-4.0.3 work-1.04 §6.4): rather than risk an OOM mid-migration (which would leave the migration unfinishable) or ship a half-correct phased path, the codec pass refuses with zero destructive writes. The caller can either declare an available-memory budget via Config to raise the single-txn ceiling, or use the offline pulsedb migrate tool (VS-4.0.4) for very large stores.

store_size is the on-disk file size at open; projected_peak is the conservative peak-RSS estimate (store_size × coefficient); budget is the single-txn ceiling that was exceeded.

Fields

store_size: u64

On-disk redb file size at open, in bytes.

projected_peak: u64

Conservative peak-RSS estimate for a single-txn re-encode, in bytes.

budget: u64

The single-txn budget (ceiling) that projected_peak exceeded, in bytes.

SubstrateMigrationInsufficientDisk

The bincode→postcard codec migration cannot run because there is not enough free disk space to hold the pristine .pre-substrate.bak backup plus the migrated file plus a redb transaction-growth margin.

This is the disk axis of the unified headroom preflight (VS-4.0.3 work-1.05 / audit C3), the companion of Self::SubstrateMigrationTooLarge (the memory axis). The pristine backup taken before any destructive write (.pre-substrate.bak) roughly doubles the on-disk footprint, and the postcard re-encode does not shrink the size-dominant Vec<f32> embedding table, so the migrated file is conservatively assumed to be ~1× the store size. The preflight fails here with zero destructive writes (no half-migration that runs the disk out mid-pass) rather than risk an unfinishable migration. Free up disk, or run the offline pulsedb migrate tool (VS-4.0.4) for very large stores.

store_size is the on-disk file size at open; required is the conservative free-space estimate (backup ≈ store_size + migrated ≈ store_size + redb txn-growth margin); available is the free space observed on the store’s filesystem at open.

Fields

store_size: u64

On-disk redb file size at open, in bytes.

required: u64

Conservative free-space estimate the migration needs, in bytes.

available: u64

Free space observed on the store’s filesystem at open, in bytes.

SubstrateMigrationRequiresSync

The bincode→postcard codec migration was attempted by a build without the sync feature, but the database contains sync_cursors rows written by a prior sync-enabled build. Those rows can only be re-encoded by a build that knows the SyncCursor type, so completing the migration here would leave them bincode-encoded under a postcard marker — silent corruption a later sync build would hit reading them as postcard. The migration fails closed with no marker bump (the store stays re-migratable) so a sync-enabled build can finish it.

Implementations

impl StorageError

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

Creates a corruption error with the given message.

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

Creates a transaction error with the given message.

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

Creates a serialization error with the given message.

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

Creates a redb error with the given message.

pub fn substrate_upgrade_required(found: u8, current: u8) -> Self

Creates a substrate-upgrade-required error.

found is the substrate format stored in the database (0 = pre-4.0 bincode era), current is the format this build writes.

pub fn substrate_format_too_new(found: u8, current: u8) -> Self

Creates a substrate-format-too-new error (forward-incompatibility).

pub fn substrate_migration_too_large( store_size: u64, projected_peak: u64, budget: u64, ) -> Self

Creates a substrate-migration-too-large error (single-txn ceiling exceeded).

pub fn substrate_migration_insufficient_disk( store_size: u64, required: u64, available: u64, ) -> Self

Creates a substrate-migration-insufficient-disk error (disk-headroom axis).

Trait Implementations

impl Debug for StorageError

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

Formats the value using the given formatter.

impl Display for StorageError

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

Formats the value using the given formatter.

impl Error for StorageError

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<CommitError> for StorageError

fn from(err: CommitError) -> Self

Converts to this type from the input type.

impl From<DatabaseError> for StorageError

fn from(err: DatabaseError) -> Self

Converts to this type from the input type.

impl From<Error> for StorageError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for StorageError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<StorageError> for PulseDBError

fn from(source: StorageError) -> Self

Converts to this type from the input type.

impl From<StorageError> for StorageError

fn from(err: StorageError) -> Self

Converts to this type from the input type.

impl From<TableError> for StorageError

fn from(err: TableError) -> Self

Converts to this type from the input type.

impl From<TransactionError> for StorageError

fn from(err: TransactionError) -> Self

Converts to this type from the input type.