Enum WalError 

pub enum WalError {
    Io(Error),
    ChecksumMismatch {
        lsn: u64,
        expected: u32,
        actual: u32,
    },
    CheckpointCorrupt {
        path: String,
        detail: String,
    },
    InvalidMagic {
        offset: u64,
        expected: u32,
        actual: u32,
    },
    UnsupportedVersion {
        version: u16,
        supported: u16,
    },
    SegmentFormatVersion {
        path: String,
        version: u16,
        supported: u16,
    },
    UnknownRequiredRecordType {
        record_type: u32,
        lsn: u64,
    },
    PayloadTooLarge {
        size: usize,
        max: usize,
    },
    Sealed,
    AlignmentViolation {
        context: &'static str,
        required: usize,
        actual: usize,
    },
    LockPoisoned {
        context: &'static str,
    },
    EncryptionError {
        detail: String,
    },
    EncryptedRecordWithoutKey {
        lsn: u64,
        context: &'static str,
    },
    DwbOffNotOpenable,
    CorruptRecord {
        lsn: u64,
        detail: String,
    },
    InvalidPayload {
        detail: String,
    },
    DirectIoUnsupported {
        path: String,
    },
    OutOfSpace {
        context: &'static str,
    },
    DurabilityLost {
        detail: String,
    },
    MidFileCorruption {
        path: String,
        offset: u64,
        resync_offset: u64,
        resync_lsn: u64,
    },
    SegmentLsnGap {
        path: String,
        previous_path: String,
        previous_last_lsn: u64,
        expected_lsn: u64,
        found_lsn: u64,
    },
    SegmentOverlapsPrevious {
        path: String,
        first_lsn: u64,
        previous_path: String,
        previous_last_lsn: u64,
    },
    RollCleanupFailed {
        path: String,
        roll: Box<WalError>,
        cleanup: Box<WalError>,
    },
    ReplayBelowRetainedFloor {
        from_lsn: u64,
        retained_floor_lsn: u64,
        earliest_segment: String,
    },
}

Errors produced by the WAL subsystem.

Variants

Io(Error)

I/O error from the underlying file operations.

ChecksumMismatch

CRC32C checksum mismatch during read/replay.

Fields

lsn: u64

expected: u32

actual: u32

CheckpointCorrupt

Checkpoint frame is corrupt: bad version, truncated payload, or CRC mismatch.

Fields

path: String

detail: String

InvalidMagic

Record header has an invalid magic number — file is corrupted or not a WAL.

Fields

offset: u64

expected: u32

actual: u32

UnsupportedVersion

WAL format version is not supported by this binary.

Fields

version: u16

supported: u16

SegmentFormatVersion

A segment holds records in a WAL format version this build cannot read.

The same finding as WalError::UnsupportedVersion, reported by the callers that know which file carries it. A reader sees one header at a time and holds no path, and a version alone does not tell an operator which segment to act on.

Fields

path: String

version: u16

supported: u16

UnknownRequiredRecordType

Unknown required record type encountered during replay. Optional unknown record types are safely skipped.

Fields

record_type: u32

lsn: u64

PayloadTooLarge

Write payload exceeds maximum record size.

Fields

size: usize

max: usize

Sealed

Attempted to write to a WAL that has been closed or is in error state.

AlignmentViolation

Alignment violation — O_DIRECT requires aligned buffers and offsets.

Fields

context: &'static str

required: usize

actual: usize

LockPoisoned

A mutex was poisoned (another thread panicked while holding the lock).

Fields

context: &'static str

EncryptionError

Encryption or decryption failed.

Fields

detail: String

EncryptedRecordWithoutKey

A record still carries ENCRYPTED_FLAG at a point where plaintext is required, and no key ring is available to turn it back into plaintext.

Passing the ciphertext through would hand every downstream decoder bytes it cannot parse: the lucky ones fail with a confusing framing error, the unlucky ones decode garbage into engine state. Skipping the record would silently drop a committed write. Neither is recoverable at this layer, so the only honest outcome is to refuse to replay.

Fields

lsn: u64

context: &'static str

DwbOffNotOpenable

DoubleWriteBuffer::open was called with DwbMode::Off. Callers that want the DWB disabled must not call open at all.

CorruptRecord

Record payload failed structural validation (truncation, bad length prefix, invalid UTF-8, etc.). Distinct from WalError::ChecksumMismatch — the bytes passed CRC but the payload’s own framing is wrong.

Fields

lsn: u64

detail: String

InvalidPayload

Record payload is structurally invalid at parse time, before the surrounding LSN context is known (e.g., anchor payload decoded from a byte slice during unit-level use).

Fields

detail: String

DirectIoUnsupported

The filesystem holding the WAL cannot open files with O_DIRECT.

Most overlayfs configurations, many network filesystems, and tmpfs before Linux 6.1 reject O_DIRECT at open(2) with EINVAL. Kept distinct from a generic WalError::Io because the operator action is specific — relocate the data directory or opt out of direct I/O deliberately — and because silently continuing with buffered I/O would downgrade the WAL’s durability guarantee without anyone being told.

Fields

path: String

OutOfSpace

The filesystem ran out of space while appending to the WAL (ENOSPC).

Distinct from a generic WalError::Io so callers can stop acknowledging writes and surface a specific operator action instead of retrying a write that cannot succeed.

Fields

context: &'static str

DurabilityLost

An fsync of the WAL segment failed, so the writer is poisoned and permanently refuses further work.

A failed fsync is terminal, not transient. Linux reports a writeback error exactly once (errseq_t) and drops the dirty pages that failed, so the bytes the writer already handed to the page cache are gone and no retry can put them back. Continuing to serve would let a later sync see an empty buffer, report success, and acknowledge records that no longer exist anywhere. The only correct move at this layer is to stop: the segment must be re-opened from what is actually on disk.

Fields

detail: String

MidFileCorruption

A WAL segment is damaged in the middle: a valid record was found after the damaged region, so it cannot be the unfsynced tail of the last write.

Stopping at the damage point and calling everything before it “the committed prefix” would silently discard the committed records that follow, so recovery refuses to proceed instead.

Fields

path: String

offset: u64

resync_offset: u64

resync_lsn: u64

SegmentLsnGap

Two surviving WAL segments are not contiguous: the later segment’s declared first LSN is above the LSN that follows the end of the earlier one, so a whole segment is missing from the middle of the log.

Concatenating the two would hand recovery a record stream with a silent hole in it, so replay refuses instead. A missing prefix is legal (checkpoint truncation deletes whole segments below the checkpoint) and does not produce this error.

Fields

path: String

previous_path: String

previous_last_lsn: u64

expected_lsn: u64

found_lsn: u64

SegmentOverlapsPrevious

The last segment starts at or below an LSN an earlier segment already holds. An interrupted roll created it while the earlier segment stayed active. Resuming it would reissue LSNs, so the WAL refuses to open.

Fields

path: String

first_lsn: u64

previous_path: String

previous_last_lsn: u64

RollCleanupFailed

A segment roll failed, and removing the segment file it created also failed. The next open refuses that file with SegmentOverlapsPrevious.

Fields

path: String

roll: Box<WalError>

cleanup: Box<WalError>

ReplayBelowRetainedFloor

A replay was asked for the suffix starting at from_lsn, but the WAL no longer retains it: checkpoint truncation has already deleted every segment below retained_floor_lsn.

Filtering the surviving records by lsn >= from_lsn would hand the caller a shorter suffix that is indistinguishable from a complete one — no hole, no gap between surviving segments, just fewer records than the caller’s own bookkeeping says it must observe. A consumer that treats that as complete advances its watermark past records it never saw, and every effect keyed on them (change data capture, triggers, streaming materialized views) is lost with nothing recorded anywhere.

Truncation is supposed to hold below every consumer’s watermark, so this is a broken invariant rather than an expected outcome; the error exists so a residual violation is loud instead of silent.

Fields

from_lsn: u64

retained_floor_lsn: u64

earliest_segment: String

Trait Implementations

impl Debug for WalError

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

Formats the value using the given formatter.

impl Display for WalError

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

Formats the value using the given formatter.

impl Error for WalError

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<Error> for WalError

fn from(source: Error) -> Self

Converts to this type from the input type.