document clustering path

Error message

document clustering path `{:?}` must not contain empty components

What it means

JsonPath::validate for doc clustering rejects paths containing empty components, e.g. a field path like `a..b` or a leading/trailing dot. Empty path components would resolve to nothing and indicate a malformed field path.

Solutions

Fix the path to have non-empty segments separated by single dots, e.g. `attributes.service.name` instead of `attributes..service.name`.
Strip leading/trailing dots from the field path.
If the path is built programmatically, filter or join segments that skip empty strings: `parts.filter(|p| !p.is_empty()).join(".")`.

Example fix

# before
- field: log..message
# after
- field: log.message

Defensive patterns

Strategy: validation

Validate before calling

function hasNoEmptyComponents(path) {
  return String(path).split('.').every(seg => seg.length > 0);
}
// apply to every clustering method field path

Type guard

const isValidPath = (p) => typeof p === 'string' && p.length > 0 && !p.startsWith('.') && !p.endsWith('.') && !p.includes('..');

Prevention

Join path segments with a helper that skips empty strings instead of raw string concatenation.
Never hand-type double dots in dotted field paths; validate with a regex like /^[^\.]+(\.[^\.]+)*$/.
Copy dotted paths from the index schema mapping, not by hand.

When it happens

Trigger: Declaring a clustering method whose `field` path contains `..`, a leading `.`, or a trailing `.` (or a segment that is an empty string in the structured path form), validated via policy.validate() during config build.

Common situations: Hand-editing YAML dotted paths and leaving double dots; string concatenation to build paths in scripts (`prefix + "." + suffix` with empty suffix); copy-paste from JSON pointer syntax with wrong separators.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

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

        serializer.serialize_str(&self.0.join(JSON_PATH_SEPARATOR))
    }
}

impl<'de> Deserialize<'de> for JsonPath {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where D: Deserializer<'de> {
        let path = String::deserialize(deserializer)?;
        let json_path: Box<[String]> = path
            .split(JSON_PATH_SEPARATOR)
            .map(ToString::to_string)
            .collect();
        Ok(Self(json_path))
    }
}

impl JsonPath {
    fn validate(&self) -> anyhow::Result<()> {
        ensure!(
            !self.iter().any(|path_component| path_component.is_empty()),
            "document clustering path `{:?}` must not contain empty components",
            self
        );
        ensure!(
            !self
                .iter()
                .any(|path_component| path_component.trim() != path_component),
            "document clustering path `{:?}` must not contain leading or trailing whitespace",
            self
        );
        Ok(())
    }
}

impl Deref for JsonPath {
    type Target = [String];

View on GitHub (pinned to a39730c5cd)