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

missing recovery index UID

Error message

missing recovery index UID

What it means

During deserialization/recovery of SplitMetadata from its backward-compatible field-by-field format, index_uid is optional in the wire format but mandatory on the struct. When the persisted split metadata lacks an index UID, the constructor rejects the data with this error instead of silently producing a split that cannot be attributed to any index.

Source

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

            (None, None) => None,
            (Some(start), Some(end)) => {
                bail!("invalid recovery time range: start {start} is after end {end}")
            }
            _ => bail!("recovery time range must contain both start and end"),
        };
        ensure!(
            !footer_offsets.is_empty(),
            "invalid recovery footer offsets"
        );
        let maturity = match maturation_period_millis {
            Some(maturation_period_millis) => SplitMaturity::Immature {
                maturation_period: Duration::from_millis(maturation_period_millis),
            },
            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))
    }

View on GitHub (pinned to a39730c5cd)

Solutions

  1. Restore the missing index_uid in the split metadata record (from the index directory layout, metastore backup, or the split's .quickwit/ metadata).
  2. Verify the integrity of the metastore/split files — truncation can drop trailing fields.
  3. If the split is unrecoverable, delete the orphan split record so the metastore stops trying to load it.
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

When it happens

Trigger: Loading a split metadata file (or JSONL metastore record) written by an old Quickwit version or corrupted such that the index_uid field is absent when Self::from parts reconstructs the metadata.

Common situations: Restoring metastore data from a partial backup; manually edited split metadata files; migrating data from a version that serialized index UID elsewhere.

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

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