new doc mapping UID should differ from the current one, curr

Error message

new doc mapping UID should differ from the current one, current UID `{}`, new UID `{}`

What it means

prepare_doc_mapping_update checks that a doc mapping update is actually a change: every accepted update must bump doc_mapping_uid (a monotonically increasing version). If the proposed mapping has the same UID as the current one, Quickwit rejects it, treating an unchanged UID as an accidental no-op or replayed update rather than silently applying it.

Source

Thrown at quickwit/quickwit-config/src/index_config/mod.rs:728

///    - The tokenizers should be a superset of the current tokenizers
///    - A doc mapper can be built from the new doc mapping
pub fn prepare_doc_mapping_update(
    mut new_doc_mapping: DocMapping,
    current_doc_mapping: &DocMapping,
    search_settings: &SearchSettings,
) -> anyhow::Result<(DocMapping, bool)> {
    // Save the new doc mapping UID in a temporary variable and override it with the current doc
    // mapping UID to compare the two doc mappings, ignoring their UIDs.
    let new_doc_mapping_uid = new_doc_mapping.doc_mapping_uid;
    new_doc_mapping.doc_mapping_uid = current_doc_mapping.doc_mapping_uid;

    if new_doc_mapping == *current_doc_mapping {
        return Ok((new_doc_mapping, false));
    }
    // Restore the new doc mapping UID.
    new_doc_mapping.doc_mapping_uid = new_doc_mapping_uid;

    ensure!(
        new_doc_mapping.doc_mapping_uid != current_doc_mapping.doc_mapping_uid,
        "new doc mapping UID should differ from the current one, current UID `{}`, new UID `{}`",
        current_doc_mapping.doc_mapping_uid,
        new_doc_mapping.doc_mapping_uid,
    );
    let new_timestamp_field = new_doc_mapping.timestamp_field.as_deref();
    let current_timestamp_field = current_doc_mapping.timestamp_field.as_deref();
    ensure!(
        new_timestamp_field == current_timestamp_field,
        "updating timestamp field is not allowed, current timestamp field `{}`, new timestamp \
         field `{}`",
        current_timestamp_field.unwrap_or("none"),
        new_timestamp_field.unwrap_or("none"),
    );
    // TODO: Unsure this constraint is required, should we relax it?
    let new_tokenizers: HashSet<_> = new_doc_mapping.tokenizers.iter().collect();
    let current_tokenizers: HashSet<_> = current_doc_mapping.tokenizers.iter().collect();
    ensure!(

View on GitHub (pinned to a39730c5cd)

Solutions

Assign a new doc_mapping_uid greater than the current one before submitting the update
If using load_index_config_update/from file, ensure the new mapping carries a distinct UID
If the mapping truly did not change, skip the update call entirely

Example fix

// before
new_doc_mapping.doc_mapping_uid = current_doc_mapping.doc_mapping_uid;
// after
new_doc_mapping.doc_mapping_uid = current_doc_mapping.doc_mapping_uid + 1;

Defensive patterns

Strategy: validation

Validate before calling

// Rust precheck
assert_ne!(new_doc_mapping.doc_mapping_uid, current_doc_mapping.doc_mapping_uid, "bump doc_mapping_uid before update");

Prevention

Always increment doc_mapping_uid on every mapping change
Don't resubmit stale update payloads; regenerate the UID each time
Skip the update call when nothing in the mapping changed

When it happens

Trigger: Calling update_index / IndexConfig update path with a new doc mapping whose doc_mapping_uid equals the current one; client code copying the existing mapping without regenerating the UID; replaying a stale update request.

Common situations: Automation that patches index config but forgets to increment doc_mapping_uid; resubmitting the same update after a failure without bumping the UID; hand-crafted update payloads in tests/scripts.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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