quickwit-oss/quickwit · error · anyhow::Error

missing recovery doc mapping UID

Error message

missing recovery doc mapping UID

What it means

Same reconstruction path as the missing index UID error, but for doc_mapping_uid: the persisted split metadata must carry the doc mapping UID that produced the split. When the optional field is absent during recovery, the constructor fails with this error to preserve the invariant that every split references its doc mapping version.

Source

Thrown at quickwit/quickwit-metastore/src/split_metadata.rs:244

            None => SplitMaturity::Mature,
        };
        let split_metadata = Self {
            split_id: split_id.into(),
            index_uid: index_uid.ok_or_else(|| anyhow::anyhow!("missing recovery index UID"))?,
            partition_id,
            source_id,
            node_id,
            num_docs: num_docs.try_into()?,
            uncompressed_docs_size_in_bytes: uncompressed_docs_size_bytes,
            time_range,
            create_timestamp,
            maturity,
            tags: tags.into_iter().collect(),
            footer_offsets,
            delete_opstamp,
            num_merge_ops: num_merge_ops.try_into()?,
            doc_mapping_uid: doc_mapping_uid
                .ok_or_else(|| anyhow::anyhow!("missing recovery doc mapping UID"))?,
        };
        let parent_split_ids = parent_split_ids.into_iter().map(SplitId::from).collect();
        Ok((split_metadata, parent_split_ids))
    }

    /// Creates a new instance of split metadata.
    pub fn new(
        split_id: SplitId,
        index_uid: IndexUid,
        partition_id: u64,
        source_id: SourceId,
        node_id: String,
    ) -> Self {
        Self {
            split_id,
            index_uid,
            partition_id,
            source_id,

View on GitHub (pinned to a39730c5cd)

Solutions

1. Restore doc_mapping_uid in the metadata record from an index metadata backup (index config's doc mapping UID).
2. Re-ingest/re-index the affected splits if the source metadata cannot be recovered.
3. Check file integrity — truncated records can end before optional fields.

// before loading split metadata
let raw: serde_json::Value = serde_json::from_str(&text)?;
if raw.get("doc_mapping_uid").is_none() {
    eprintln!("split metadata missing doc_mapping_uid; restore from index config");
}

match SplitMetadata::try_from(raw) {
    Err(e) if e.to_string().contains("missing recovery doc mapping UID") => {
        // recover doc_mapping_uid from the index metadata or quarantine the record
    }
    other => other?,
}

When it happens

Trigger: Deserializing split metadata whose doc_mapping_uid field is missing (old format, hand-edited, or truncated record) while building SplitMetadata via the recovery constructor.

Common situations: Metastore backups restored from incompatible versions; corrupted JSONL metastore logs; manual cleanup that removed doc mapping UID fields.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• missing recovery index UID
• invalid recovery footer offsets
• source `{}` is defined more than once
• invalid recovery time range: start {start} is after end {end
• 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/347d83b2032511fe. Report an issue: GitHub.