quickwit-oss/quickwit · error

missing file `{}` in split bundle

Error message

missing file `{}` in split bundle

What it means

Quickwit packs multiple files (hotcache, postings, etc.) into a single split bundle file. fetch_file_from_split reads the split tail, parses the embedded BundleFileRanges directory, and looks up the requested path. If the requested file path is not among the bundle's recorded ranges, this error is returned, meaning the file isn't present in this split bundle.

Source

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

        storage: Arc<dyn Storage>,
        bundle_filepath: PathBuf,
        split_path: &Path,
        split_len: u64,
    ) -> anyhow::Result<(OwnedBytes, Range<u64>)> {
        let (split_bytes, footer_range) = fetch_split_tail(
            storage.as_ref(),
            split_path,
            split_len,
            DEFAULT_SPLIT_TAIL_WINDOW_NUM_BYTES,
        )
        .await?;

        // Parse the bundle file ranges from the split bytes.
        let tail_start = split_len - split_bytes.len() as u64;
        let (file_ranges, _hotcache) =
            BundleFileRanges::open_from_split_bytes(split_bytes.clone())?;
        let file_range = file_ranges.get(&bundle_filepath).ok_or_else(|| {
            anyhow::anyhow!(
                "missing file `{}` in split bundle",
                bundle_filepath.display()
            )
        })?;
        ensure!(
            file_range.start <= file_range.end,
            "bundled file range starts after it ends"
        );
        ensure!(
            file_range.end <= footer_range.start,
            "bundled file range overlaps split footer"
        );

        // If the initial tail also contains the file, reuse it and complete in one GET (at least).
        // Otherwise, fetch the file with an additional GET.
        let file_bytes = if file_range.start >= tail_start {
            let relative_start = (file_range.start - tail_start) as usize;
            let relative_end = (file_range.end - tail_start) as usize;

View on GitHub (pinned to a39730c5cd)

Solutions

1. Verify the file path exists in the split: list the split's contents (e.g. via quickwit tool inspect-split / extract-split) before fetching.
2. Ensure you are reading the correct split file for the requested resource — the file may live in another split.
3. Re-download or re-stage the split if it may be corrupted/truncated, then retry.
4. If old splits lack the file, re-index or migrate splits to the current format.

// List bundle contents before fetching
let contents = split_inspector.list_files(split_id).await?;
if !contents.contains(file_path) { return Err(anyhow!("{file_path} not in split {split_id}")); }

match storage.fetch_file_from_split(split_path, file_path).await {
    Err(e) if e.to_string().contains("missing file") => {
        // fall back to the standalone (non-bundled) file path
        storage.get_slice(&standalone_path, range).await
    }
    r => r,
}

When it happens

Trigger: Calling fetch_file_from_split (via BundleStorage open/read of a bundled file) with a bundle_filepath that was not packed into the split — wrong file path, file belonging to a different split, or a split written by an older format lacking the file.

Common situations: Search/merge code requesting hotcache or auxiliary files from a split where they don't exist; version mismatch between split format and reader; corrupted or truncated split bundles whose directory parsed but is incomplete.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• `append_records` should be called with `position_opt: None`
• failed to run mrecordlog operation
• stdin cannot be checkpointed
• Unexpected span kind: {}
• `{}` not found in storage

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