risingwavelabs/risingwave · error · anyhow::Error

initial epoch {} greater than aligned initial epoch {}

Error message

initial epoch {} greater than aligned initial epoch {}

What it means

While consuming the log to align with the sink's initial_epoch, the coordinator compares each item's epoch with initial_epoch. If an item's epoch is Greater than the aligned initial epoch, the stream has skipped past the expected initial epoch, meaning the log and the sink state are inconsistent, so it returns an error instead of breaking at the aligned epoch.

Source

Thrown at src/connector/src/sink/coordinate.rs:120

                    sink_id = %self.param.sink_id,
                    "initial epoch not matched aligned initial epoch"
                );
                let mut peeked_first = Some(first_item);
                first_item = loop {
                    let (epoch, item) = if let Some(peeked_first) = peeked_first.take() {
                        peeked_first
                    } else {
                        log_reader.next_item().await?
                    };
                    match epoch.cmp(&aligned_initial_epoch) {
                        Ordering::Less => {
                            continue;
                        }
                        Ordering::Equal => {
                            break (epoch, item);
                        }
                        Ordering::Greater => {
                            return Err(anyhow!(
                                "initial epoch {} greater than aligned initial epoch {}",
                                initial_epoch,
                                aligned_initial_epoch
                            )
                            .into());
                        }
                    }
                };
            }
        }

        let mut first_item = Some(first_item);

        #[derive(Debug)]
        enum LogConsumerState {
            /// Mark that the log consumer is not initialized yet
            Uninitialized,

View on GitHub (pinned to 6469eb736d)

Solutions

1. Verify the initial_epoch passed to the coordinator matches an epoch actually present in the log store.
2. Recover from the last valid checkpoint so initial_epoch aligns with a logged epoch.
3. Check meta-side epoch bookkeeping after scale-out/schema change for dropped log entries.

if err.to_string().contains("greater than aligned initial epoch") {
    // recompute initial_epoch from the last valid checkpoint and retry recovery
}

When it happens

Trigger: consume_log_and_sink with initial_epoch set; the log reader yields an item whose epoch is greater than initial_epoch before an Equal match, i.e. no log entry exactly matches the sink's initial epoch.

Common situations: Failover recovery where the sink's initial epoch is ahead of the log store's retained epochs; version mismatch after schema change or incorrect epoch propagation from meta during sink scaling.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• log_store_rewind_start_epoch {} not later than first_epoch {
• newly start epoch {} after update vnode bitmap not matched w
• Iceberg metadata scan should not have input executors
• Chunk size can't be zero!
• Invalid time: {value} {unit} is out of range for a time of d

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