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.

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)

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

• execute_merge_operation: sources.len() ({}) != op.splits.len
• attempted to merge zero splits
• doc mapper must be present if there are delete tasks
• timestamp_secs must be UInt64 or Int64 for MC-3 check
• recovery time range must contain both start and end

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