quickwit-oss/quickwit · error

attempted to merge splits with different doc mapping uid

Error message

attempted to merge splits with different doc mapping uid

What it means

`merge_split_attrs` verifies that all splits scheduled for a merge share the same `doc_mapping_uid`, which identifies the doc mapper version that produced them. Merging splits from different mapping versions would produce an inconsistent merged split, so it is refused.

Solutions

1. Wait for the publisher/merge pipeline to drain, or exclude splits with an older `doc_mapping_uid` from the merge batch.
2. Re-trigger merge scheduling so it groups splits by doc mapping version.
3. If old-generation splits are obsolete, let retention/delete tasks remove them instead of merging.

fn merges_are_compatible(splits: &[Split]) -> bool {
    let uid = splits[0].doc_mapping_uid;
    splits.iter().all(|s| s.doc_mapping_uid == uid)
}

match merge_split_attrs(&splits, &pipeline_id) {
    Ok(attrs) => { /* proceed with merge */ }
    Err(e) if e.to_string().contains("different doc mapping uid") => {
        // skip/regroup this merge batch by doc_mapping_uid
    }
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: A merge task (via `process_merge` or `fake_merge`) receives a list of splits whose `doc_mapping_uid` values differ — typically stale splits left over after the index config's schema was changed and reloaded.

Common situations: Index config updated (new doc mapping uid) while older splits from the previous mapping still exist; control plane scheduling a merge across mapping-version boundaries; replayed or copied splits from an older index generation.

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

• attempted to merge zero splits
• doc mapper must be present if there are delete tasks
• execute_merge_operation: sources.len()
• expected LargeStringArray for service col page
• failed to find offset for split

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

Appendix: source

Thrown at quickwit/quickwit-indexing/src/actors/merge_executor.rs:299

    let num_docs = sum_num_docs(splits);
    let replaced_split_ids: Vec<SplitId> = splits
        .iter()
        .map(|split| split.split_id().clone())
        .collect();
    let delete_opstamp = splits
        .iter()
        .map(|split| split.delete_opstamp)
        .min()
        .unwrap_or(0);
    let doc_mapping_uid = splits
        .first()
        .ok_or_else(|| anyhow::anyhow!("attempted to merge zero splits"))?
        .doc_mapping_uid;
    if splits
        .iter()
        .any(|split| split.doc_mapping_uid != doc_mapping_uid)
    {
        anyhow::bail!("attempted to merge splits with different doc mapping uid");
    }
    Ok(SplitAttrs {
        node_id: pipeline_id.node_id.clone(),
        index_uid: pipeline_id.index_uid.clone(),
        source_id: pipeline_id.source_id.clone(),
        doc_mapping_uid,
        split_id: merge_split_id,
        partition_id,
        replaced_split_ids,
        time_range,
        num_docs,
        uncompressed_docs_size_in_bytes,
        delete_opstamp,
        num_merge_ops: max_merge_ops(splits) + 1,
    })
}

fn max_merge_ops(splits: &[SplitMetadata]) -> usize {

View on GitHub (pinned to a39730c5cd)