What causes "split footer starts after its trailer" in quickwit-oss/quickwit?

Re-upload or re-index the split to regenerate a consistent footer trailer.

split footer starts after its trailer

Error message

split footer starts after its trailer

What it means

When a modern split footer trailer is found, the footer start offset it records must fall at or before the trailer's position (split_len minus the trailer size). A footer start beyond the trailer means the trailer's offset is corrupt or the split layout is inconsistent, so the library refuses to compute the footer range.

Source

Thrown at quickwit/quickwit-storage/src/bundle_storage.rs:258

    Ok(footer_start..split_len)
}

fn locate_split_footer_range_in_tail(
    split_len: u64,
    tail_bytes: &[u8],
) -> anyhow::Result<FooterLocation> {
    // Legacy split layout:
    // [body][bundle metadata][metadata len][hotcache][hotcache len]
    ensure!(
        tail_bytes.len() as u64 <= split_len,
        "split tail is longer than the split itself"
    );
    let trailer_start = tail_bytes
        .len()
        .checked_sub(SPLIT_FOOTER_TRAILER_NUM_BYTES)
        .context("split tail is too short to contain a footer trailer")?;
    if let Some(footer_start) = deserialize_split_footer_trailer(&tail_bytes[trailer_start..])? {
        ensure!(
            footer_start <= split_len - SPLIT_FOOTER_TRAILER_NUM_BYTES as u64,
            "split footer starts after its trailer"
        );
        return Ok(FooterLocation::Located(footer_start..split_len));
    }

    let hotcache_len =
        u32::from_le_bytes(tail_bytes[tail_bytes.len() - HOTCACHE_LEN_NUM_BYTES..].try_into()?)
            as u64;
    let bundle_metadata_len_end = split_len
        .checked_sub(HOTCACHE_LEN_NUM_BYTES as u64)
        .and_then(|offset| offset.checked_sub(hotcache_len))
        .context("split footer exceeds split length")?;
    let bundle_metadata_len_start = bundle_metadata_len_end
        .checked_sub(BUNDLE_METADATA_LEN_NUM_BYTES as u64)
        .context("split footer exceeds split length")?;
    let bundle_metadata_len_range = bundle_metadata_len_start..bundle_metadata_len_end;
    let tail_start = split_len - tail_bytes.len() as u64;

View on GitHub (pinned to a39730c5cd)

Solutions

Re-upload or re-index the split to regenerate a consistent footer trailer.
Verify the split object's integrity against its checksum; restore from source if corrupted.
Check for processes modifying split files in place and prevent such overwrites.

Defensive patterns

Strategy: try-catch

Try / catch

match locate_split_footer_range(split, &storage).await {
    Ok(f) => f,
    Err(e) if e.to_string().contains("footer starts after its trailer") => {
        // split tail is corrupt: re-index or re-upload the split
    }
    Err(e) => return Err(e.into()),
}

Prevention

Treat split files in object storage as immutable; always replace with new objects.
Verify checksums of tail bytes when copying or backing up splits.
Alert on any object-store write operations targeting existing split paths.

When it happens

Trigger: Calling `locate_split_footer_range` / `fetch_split_tail` on a split whose trailer's `footer_start_inclusive` value exceeds `split_len - SPLIT_FOOTER_TRAILER_NUM_BYTES`, e.g. corrupted trailer bytes or a trailer from a longer prior version of the file.

Common situations: Split files partially overwritten (trailer kept, body changed or truncated); corrupted bytes in the tail; in-place object edits that invalidated the recorded footer offset.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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