What causes "invalid recovery footer offsets" in quickwit-oss/quickwit?

Delete or re-stage the affected split so the indexing pipeline rewrites a complete metadata record.

invalid recovery footer offsets

Error message

invalid recovery footer offsets

What it means

When deserializing a SplitMetadata from its serialized recovery form (try_from_recovery_metadata), the recovery footer offsets are expected to be a non-empty set. An empty footer offset list means the stored recovery record is incomplete or corrupted, so the library refuses to reconstruct the split metadata. This guards the metastore against silently indexing a split with no footer information.

Source

Thrown at quickwit/quickwit-metastore/src/split_metadata.rs:218

            uncompressed_docs_size_bytes,
            time_range_start_inclusive,
            time_range_end_inclusive,
            create_timestamp,
            tags,
            delete_opstamp,
            num_merge_ops,
            parent_split_ids,
            maturation_period_millis,
        } = recovery_metadata;
        let time_range = match (time_range_start_inclusive, time_range_end_inclusive) {
            (Some(start), Some(end)) if start <= end => Some(start..=end),
            (None, None) => None,
            (Some(start), Some(end)) => {
                bail!("invalid recovery time range: start {start} is after end {end}")
            }
            _ => bail!("recovery time range must contain both start and end"),
        };
        ensure!(
            !footer_offsets.is_empty(),
            "invalid recovery footer offsets"
        );
        let maturity = match maturation_period_millis {
            Some(maturation_period_millis) => SplitMaturity::Immature {
                maturation_period: Duration::from_millis(maturation_period_millis),
            },
            None => SplitMaturity::Mature,
        };
        let split_metadata = Self {
            split_id: split_id.into(),
            index_uid: index_uid.ok_or_else(|| anyhow::anyhow!("missing recovery index UID"))?,
            partition_id,
            source_id,
            node_id,
            num_docs: num_docs.try_into()?,
            uncompressed_docs_size_in_bytes: uncompressed_docs_size_bytes,
            time_range,

View on GitHub (pinned to a39730c5cd)

Solutions

Delete or re-stage the affected split so the indexing pipeline rewrites a complete metadata record.
Check which Quickwit version wrote the record; upgrade and re-index if an old version produced empty footers.
If the record is recoverable from a backup, restore the metastore row including footer offsets.

Defensive patterns

Strategy: validation

Validate before calling

if recovery_metadata.footer_offsets.is_empty() {
    // skip or quarantine this split record before calling try_from_recovery_metadata
}

Try / catch

match SplitMetadata::try_from_recovery_metadata(rec) {
    Ok(md) => md,
    Err(e) if e.to_string().contains("invalid recovery footer offsets") => {
        warn!("corrupt recovery record: {e}"); /* quarantine/delete record */
    }
    Err(e) => return Err(e),
}

Prevention

Never hand-edit metastore records; use Quickwit tooling.
Keep metastore backups so corrupt rows can be restored.
Upgrade Quickwit rather than mixing writer versions against the same metastore.

When it happens

Trigger: Calling `SplitMetadata::try_from_recovery_metadata` with a SplitMetadataFooter where the `footer_offsets` map/field is empty — typically from a truncated or partially written metastore record.

Common situations: Metastore rows written by an older or buggy Quickwit version that left footer_offsets empty; manual editing of the metastore; corrupted rows after a failed write.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

AI-assisted analysis of quickwit-oss/quickwit@a39730c5cd (2026-09-08). Data as JSON: /api/errors/47d73704d1a1cd5f. Report an issue: GitHub.