Enum StorageError 

#[non_exhaustive]
pub enum StorageError {
    RecordingDirectoryExists {
        path: PathBuf,
    },
    InvalidConfiguration {
        setting: &'static str,
        reason: String,
    },
    DuplicateStateStream {
        stream: String,
    },
    UnknownStateStream {
        stream: String,
    },
    StateWriterClosed,
    RecordingFinished,
    RecordingDirectoryInUse {
        path: PathBuf,
    },
    RecordingNotContinuable {
        path: PathBuf,
    },
    RecordingConfigurationMismatch {
        path: PathBuf,
        reason: String,
    },
    IncompleteCheckpointStream {
        stream: String,
        reason: String,
    },
    NoCheckpointState {
        stream: String,
    },
    NoRecordedState {
        stream: String,
    },
    RecoveryConflict {
        path: PathBuf,
        reason: String,
    },
    OperationalTimestamp {
        operation: &'static str,
        source: Format,
    },
    OperationalDurationOverflow,
    UnsupportedVersion {
        path: PathBuf,
        found: u32,
        supported: u32,
    },
    InvalidMetadata {
        path: PathBuf,
        reason: String,
    },
    RecordingNotComplete {
        path: PathBuf,
    },
    MissingChunk {
        path: PathBuf,
    },
    ChunkSizeMismatch {
        path: PathBuf,
        expected: u64,
        actual: u64,
    },
    ChecksumMismatch {
        path: PathBuf,
        expected: String,
        actual: String,
    },
    InvalidRecord {
        path: PathBuf,
        line: u64,
        reason: String,
    },
    StateAccess {
        stream: String,
        iteration: u64,
        field: String,
        source: StateError,
    },
    EncodeField {
        stream: String,
        iteration: u64,
        field: String,
        source: Error,
    },
    DuplicateDecoder {
        field: String,
    },
    MissingDecoder {
        field: String,
    },
    DecodeField {
        stream: String,
        iteration: u64,
        field: String,
        source: Box<dyn Error + Send + Sync + 'static>,
    },
    StateSeriesInvariant {
        stream: String,
        iteration: u64,
        source: StateSeriesError,
    },
    Io {
        operation: &'static str,
        path: PathBuf,
        source: Error,
    },
    Json {
        operation: &'static str,
        path: PathBuf,
        source: Error,
    },
    ByteCountOverflow {
        stream: String,
    },
    RecordTooLarge {
        stream: String,
        bytes: u64,
        limit: u64,
    },
    OutOfOrderIteration {
        stream: String,
        iteration: u64,
        previous: u64,
    },
    WriterQueueDisconnected,
    StateWriterTerminated {
        source: Arc<StorageError>,
    },
    StateWriterPanicked,
}

A failure encountered while encoding, writing, reading, or decoding a run.

Variants are grouped by the boundary that detects them: configuration and lifecycle, persisted-format validation, field processing, filesystem and JSON mechanics, and asynchronous writer coordination.

The enum is non-exhaustive so future integrity checks or durability modes can add precise variants without forcing downstream crates to exhaustively match every storage failure.

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.

RecordingDirectoryExists

A new recording refused to replace an existing path.

Storage never silently overwrites a previous recording. Existing running recordings are accepted only through explicit continuation.

Fields

path: PathBuf

Existing path that prevented recording creation.

InvalidConfiguration

One storage setting violates a constructor invariant.

Settings represented by NonZero* types are rejected before this point. This variant covers relationships between values, unsafe relative paths, unsupported names, and similar semantic configuration failures.

Fields

setting: &'static str

Stable setting name used by documentation and diagnostics.

reason: String

Concise explanation of the violated invariant.

DuplicateStateStream

Two logical output streams were configured with the same name.

Fields

stream: String

Repeated normalized stream name.

UnknownStateStream

A caller selected a stream absent from the recording declaration.

Fields

stream: String

Requested stream name.

StateWriterClosed

The recording-wide writer has stopped accepting new work.

RecordingFinished

A caller repeated a recording operation after successful termination.

RecordingDirectoryInUse

Another writer currently owns the recording directory.

Fields

path: PathBuf

Output root whose advisory exclusive lease could not be acquired.

RecordingNotContinuable

Explicit continuation was requested for a terminal recording.

Fields

path: PathBuf

Metadata file declaring a complete or failed lifecycle.

RecordingConfigurationMismatch

Existing running configuration differs from the requested builder.

Fields

path: PathBuf

Existing authoritative metadata document.

reason: String

Concise description of the incompatible configuration.

IncompleteCheckpointStream

A stream selected as a checkpoint omits part of the full state schema.

Fields

stream: String

Logical stream selected for latest-checkpoint reconstruction.

reason: String

Missing, additional, or reordered schema detail.

NoCheckpointState

No complete record exists from which a state can be reconstructed.

Fields

stream: String

Logical checkpoint stream searched during continuation.

NoRecordedState

A completed stream contains no record to reconstruct.

Fields

stream: String

Logical completed stream searched for its latest state.

RecoveryConflict

Chunk filenames do not describe one recoverable committed prefix and at most one highest open chunk.

Fields

path: PathBuf

Stream directory or conflicting payload path.

reason: String

Concise filename/inventory conflict.

OperationalTimestamp

The host UTC clock could not be represented in the canonical metadata timestamp format.

Fields

operation: &'static str

Lifecycle action requesting the timestamp.

source: Format

Timestamp-formatting failure.

OperationalDurationOverflow

A monotonic writer session exceeded the exact persisted duration range.

UnsupportedVersion

metadata.json declares a format version this crate cannot read.

Fields

path: PathBuf

Metadata file containing the unsupported declaration.

found: u32

Version found in the file.

supported: u32

Version implemented by this crate.

InvalidMetadata

Syntactically valid metadata violates a semantic storage invariant.

Fields

path: PathBuf

Authoritative metadata file that failed validation.

reason: String

Concise invariant violation.

RecordingNotComplete

A reader requiring a completed recording encountered terminally unsuitable metadata.

Fields

path: PathBuf

Metadata file whose lifecycle state is incomplete or failed.

MissingChunk

A committed chunk named by metadata is absent from the filesystem.

Fields

path: PathBuf

Expected chunk path.

ChunkSizeMismatch

A committed chunk’s actual length differs from its metadata descriptor.

Fields

path: PathBuf

Chunk path whose filesystem length was checked.

expected: u64

Authoritative encoded byte length from metadata.

actual: u64

Encoded byte length reported by the filesystem.

ChecksumMismatch

A committed chunk’s checksum differs from its metadata descriptor.

Fields

path: PathBuf

Chunk path whose contents were checked.

expected: String

Authoritative checksum encoded in metadata.

actual: String

Checksum computed from the chunk contents.

InvalidRecord

One syntactically readable JSONL record violates record invariants.

Fields

path: PathBuf

Chunk file containing the invalid record.

line: u64

One-based JSONL line number.

reason: String

Concise framing or semantic invariant violation.

StateAccess

The encoder could not borrow one declared field from the live state.

Fields

stream: String

Logical output stream being sampled.

iteration: u64

Iteration of the sampled state.

field: String

Declared stream field that could not be borrowed.

source: StateError

Original SystemState access failure.

EncodeField

Serde failed while encoding one borrowed payload.

Fields

stream: String

Logical output stream being encoded.

iteration: u64

Iteration of the sampled state.

field: String

Field whose payload serializer failed.

source: Error

Underlying JSON serializer failure.

DuplicateDecoder

A decoder registration attempted to reuse one field key.

Fields

field: String

Repeated state field key.

MissingDecoder

No concrete payload decoder was declared for a persisted field key.

Fields

field: String

Persisted state field key requiring reconstruction.

DecodeField

A user-supplied field decoder failed to reconstruct its concrete value.

Fields

stream: String

Logical stream being reconstructed.

iteration: u64

Iteration of the raw record.

field: String

Field whose registered decoder failed.

source: Box<dyn Error + Send + Sync + 'static>

Decoder-specific failure retained behind an object-safe boundary.

StateSeriesInvariant

A reconstructed state violated its destination series invariant.

The rejected state is intentionally not retained in this error: it was created from persisted input and is dropped on failed reconstruction, preventing an error value from pinning arbitrarily large payloads.

Fields

stream: String

Logical stream being reconstructed.

iteration: u64

Iteration of the rejected decoded state.

source: StateSeriesError

Original in-memory collection invariant failure.

Io

A filesystem operation failed.

Fields

operation: &'static str

Stable action description such as create chunk or sync metadata.

path: PathBuf

Filesystem path involved in the failed operation.

source: Error

Underlying operating-system error.

Json

JSON framing, metadata serialization, or raw record parsing failed.

Fields

operation: &'static str

Stable action description such as parse metadata.

path: PathBuf

Metadata or chunk path associated with the JSON operation.

source: Error

Underlying Serde JSON failure.

ByteCountOverflow

Exact byte accounting overflowed its u64 persisted representation.

Fields

stream: String

Logical stream whose accounting could not be represented.

RecordTooLarge

One indivisible record exceeds the stream’s strict queue-byte budget.

Returning immediately is essential: waiting for capacity can never make a record larger than the complete budget admissible.

Fields

stream: String

Logical stream that rejected the encoded record.

bytes: u64

Exact framed size of the rejected record.

limit: u64

Configured strict queue-byte limit.

OutOfOrderIteration

A stream submission did not advance its iteration.

Fields

stream: String

Logical stream receiving the record.

iteration: u64

Rejected iteration.

previous: u64

Most recently accepted iteration.

WriterQueueDisconnected

The bounded recording queue disconnected before shutdown completed.

StateWriterTerminated

The recording worker terminated with an authoritative storage failure.

The shared source lets multiple blocked submitters observe the same terminal failure without cloning an IO or JSON error.

Fields

source: Arc<StorageError>

Shared authoritative worker failure.

StateWriterPanicked

Joining a writer thread revealed an unexpected panic.

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.