quickwit-oss/quickwit · error

document clustering fingerprint policy must contain at…

Error message

document clustering fingerprint policy must contain at least one field

What it means

Within a document clustering fingerprint policy, `FingerprintPolicy::validate` requires at least one clustering method (field). A fingerprint policy with an empty `fingerprint` list cannot compute any fingerprint and is rejected.

Solutions

1. Add at least one clustering method/field entry to the policy's `fingerprint` list (e.g. a field like `level`, `service`).
2. Remove the whole empty policy from `doc_clustering.policies` if it is not needed.
3. Validate the fingerprint methods individually too — each entry must itself be a valid ClusteringMethod.

Example fix

# before
- fingerprint: []
# after
- fingerprint:
    - field: service
      method: exact

for (const p of config.doc_clustering?.policies ?? []) {
  if (Array.isArray(p.fingerprint) && p.fingerprint.length === 0) {
    throw new Error('each fingerprint policy needs at least one field');
  }
}

const isValidFingerprintPolicy = (p) => Array.isArray(p?.fingerprint) && p.fingerprint.length > 0;

When it happens

Trigger: An index config where a policy is declared but its `fingerprint` array is empty (`fingerprint: []`), surfaced through `FingerprintPolicy::validate` when DocsClusteringConfig::validate iterates the policies via build_optional/index creation.

Common situations: Templated config with placeholders never filled in; a UI or script filtering out fields but emitting the empty policy; deleting all field entries by hand during tuning.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• document clustering policies must contain at least one…
• concatenate field uses an unknown field
• contains an empty label name
• contains an empty label value
• `desired_num_pipelines` must be strictly positive

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

Appendix: source

Thrown at quickwit/quickwit-config/src/docs_clustering.rs:135

    fn validate(&self) -> anyhow::Result<()> {
        match self {
            Self::Fingerprint { fingerprint } => {
                fingerprint.validate()?;
            }
        }
        Ok(())
    }
}

#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(transparent)]
pub struct FingerprintPolicy {
    pub fingerprint: Vec<ClusteringMethod>,
}

impl FingerprintPolicy {
    fn validate(&self) -> anyhow::Result<()> {
        ensure!(
            !self.fingerprint.is_empty(),
            "document clustering fingerprint policy must contain at least one field"
        );
        for method in &self.fingerprint {
            method.validate()?;
        }
        Ok(())
    }
}

#[repr(transparent)]
#[derive(Debug, Clone, PartialEq)]
pub struct JsonPath(Box<[String]>);

impl Serialize for JsonPath {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where S: Serializer {
        serializer.serialize_str(&self.0.join(JSON_PATH_SEPARATOR))

View on GitHub (pinned to a39730c5cd)