document clustering policies must contain at least one…

Error message

document clustering policies must contain at least one policy

What it means

DocsClusteringConfig::validate enforces that a `doc_clustering` (docs mapping) configuration contains at least one clustering policy. An empty `policies` list is a useless clustering configuration, so validation rejects it with this message.

Solutions

Add at least one policy under `doc_clustering.policies` (e.g. a fingerprint policy with fields).
If clustering is not needed, remove the whole `doc_clustering` section instead of leaving an empty policies list.
Run the config validation (`quickwit index create` dry run or the validate path) locally before deploying to catch this early.

Example fix

# before
doc_clustering:
  policies: []
# after
doc_clustering:
  policies:
    - fingerprint:
        - field: level
          method: exact

Defensive patterns

Strategy: validation

Validate before calling

const policies = config.doc_clustering?.policies ?? [];
if (policies.length === 0) {
  throw new Error('doc_clustering.policies must contain at least one policy');
}

Type guard

const hasPolicies = (c) => Array.isArray(c?.doc_clustering?.policies) && c.doc_clustering.policies.length > 0;

Try / catch

try {
  const index = await qw.createIndex(config);
} catch (e) {
  if (String(e).includes('document clustering policies must contain at least one policy')) {
    // fix config: add a policy or drop the doc_clustering section
  } else throw e;
}

Prevention

Remove the entire doc_clustering section when clustering is not used, instead of leaving an empty policies array.
Lint index configs to reject empty arrays under doc_clustering.policies before submission.
When generating config programmatically, fail fast if a filter yields zero policies.

When it happens

Trigger: Defining an index config with `doc_clustering.policies: []` (or the key present but YAML/JSON yields an empty array), then calling the config builder's validate/build path (via `build_optional`) or index creation.

Common situations: Copy-pasting a clustering config template and removing all policies; programmatically generating config where a filter produced an empty list; commenting out all policy blocks but leaving the empty key.

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

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

Appendix: source

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

            return Ok(None);
        };

        match disable_override {
            Some(true) => Ok(None),
            Some(false) | None => {
                let config = DocsClusteringConfig {
                    policies: config_builder.policies,
                };
                config.validate()?;
                Ok(Some(config))
            }
        }
    }
}

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

/// Defines how documents are clustered.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(deny_unknown_fields, untagged)]
pub enum ClusteringPolicy {
    /// Clusters documents using structure and configured field fingerprints.
    Fingerprint { fingerprint: FingerprintPolicy },
}

View on GitHub (pinned to a39730c5cd)