risingwavelabs/risingwave · warning · HummockError

Wait epoch error: {0}

Error message

Wait epoch error: {0}

What it means

A reader waited for Hummock's watermark/epoch to advance past a required epoch and the wait failed, with the reason in the String payload. This occurs in the epoch-based visibility machinery when a client waits for a safe read epoch. It signals the wait for the requested epoch could not complete.

Source

Thrown at src/storage/src/hummock/error.rs:47

    #[error("Checksum mismatch: expected {expected}, found: {found}")]
    ChecksumMismatch { expected: u64, found: u64 },
    #[error("Invalid block")]
    InvalidBlock,
    #[error("Encode error: {0}")]
    EncodeError(String),
    #[error("Decode error: {0}")]
    DecodeError(String),
    #[error("ObjectStore failed with IO error: {0}")]
    ObjectIoError(
        #[from]
        #[backtrace]
        ObjectError,
    ),
    #[error("Meta error: {0}")]
    MetaError(String),
    #[error("SharedBuffer error: {0}")]
    SharedBufferError(String),
    #[error("Wait epoch error: {0}")]
    WaitEpoch(String),
    #[error("Next epoch error: {0}")]
    NextEpoch(String),
    #[error("Change log retention miss: table {table_id}, epoch {epoch}")]
    ChangeLogRetentionMiss { table_id: TableId, epoch: u64 },
    #[error("Time-travel version expired: table {table_id}, epoch {epoch}")]
    TimeTravelVersionExpired { table_id: TableId, epoch: u64 },
    #[error(
        "Committed epoch mismatch: table {table_id}, committed_epoch {committed_epoch}, read_epoch {read_epoch}"
    )]
    CommittedEpochMismatch {
        table_id: TableId,
        committed_epoch: u64,
        read_epoch: u64,
    },
    #[error("Barrier read is unavailable for now. Likely the cluster is recovering")]
    ReadCurrentEpoch,
    #[error("CompactionExecutor error: {0}")]

View on GitHub (pinned to 6469eb736d)

Solutions

1. Retry the read; transient epoch wait failures resolve once watermarks advance.
2. Check meta node and compactor health/logs for stalled heartbeat or epoch advancement.
3. Verify network connectivity between compute, meta, and storage nodes.
4. If it persists after restart, inspect watermark advancement for a stuck barrier and report to maintainers.

// Rust
match hummock_read_with_wait(...) {
    Err(e) if e.to_string().starts_with("Wait epoch error") => {
        // retry with backoff; alert if watermark does not advance
    }
    r => r?,
}

When it happens

Trigger: Calling Hummock read APIs that wait until a given epoch is available (watermark wait path) and the wait returns an error.

Common situations: Epoch/heartbeat timeout because the meta node or compute node was stalled; network partition between nodes; shutdown racing with a read that is waiting for the next epoch.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

• Next epoch error: {0}
• Change log retention miss: table {table_id}, epoch {epoch}
• Time-travel version expired: table {table_id}, epoch {epoch}
• Committed epoch mismatch: table {table_id}, committed_epoch
• Storage error: {0}

AI-assisted analysis of risingwavelabs/risingwave@6469eb736d (2026-09-11). Data as JSON: /api/errors/a9a4a5f1ac5ba9af. Report an issue: GitHub.