quickwit-oss/quickwit · error

field name `{}` must not start with a dot `.`

Error message

field name `{}` must not start with a dot `.`

What it means

Quickwit forbids field names that begin with a dot. Leading dots conflict with the nested-field path notation where dots separate parent and child fields, so a name like `.foo` is ambiguous and rejected during field mapping validation.

Source

Thrown at quickwit/quickwit-doc-mapper/src/doc_mapper/field_mapping_entry.rs:891

pub fn validate_field_mapping_name(field_mapping_name: &str) -> anyhow::Result<()> {
    static FIELD_MAPPING_NAME_PTN: LazyLock<Regex> =
        LazyLock::new(|| Regex::new(FIELD_MAPPING_NAME_PATTERN).unwrap());

    if QW_RESERVED_FIELD_NAMES.contains(&field_mapping_name) {
        bail!(
            "field name `{field_mapping_name}` is reserved. the following fields are reserved for \
             Quickwit internal usage: {}",
            QW_RESERVED_FIELD_NAMES.join(", "),
        );
    }
    if FIELD_MAPPING_NAME_PTN.is_match(field_mapping_name) {
        return Ok(());
    }
    if field_mapping_name.is_empty() {
        bail!("field name is empty");
    }
    if field_mapping_name.starts_with('.') {
        bail!(
            "field name `{}` must not start with a dot `.`",
            field_mapping_name
        );
    }
    if field_mapping_name.len() > 255 {
        bail!(
            "field name `{}` is too long. field names must not be longer than 255 characters",
            field_mapping_name
        )
    }
    let first_char = field_mapping_name.chars().next().unwrap();
    if !first_char.is_ascii_alphabetic() {
        bail!(
            "field name `{}` is invalid. field names must start with an uppercase or lowercase \
             ASCII letter, or an underscore `_`",
            field_mapping_name
        )
    }

View on GitHub (pinned to a39730c5cd)

Solutions

1. Remove the leading dot from the field name in the mapping.
2. For ES-style meta fields, rename (e.g. `_id` to `doc_id`) and configure the doc mapper accordingly.
3. If the field is nested, nest it properly (`parent.child`) instead of prefixing a dot.

Example fix

// before
{"._source": {"type": "json"}}
// after
{"source": {"type": "json"}}

fn validate_field_name(name: &str) -> Result<(), String> {
    if name.starts_with('.') {
        return Err(format!("field name `{name}` must not start with a dot"));
    }
    Ok(())
}

When it happens

Trigger: Defining a mapping field whose name starts with '.', e.g. `{"._source": {"type": "json"}}`, when calling FieldMappingEntryBuilder::default(); note names matching FIELD_MAPPING_NAME_PTN pass before this check, so the name reached the dot check via a pattern with a leading dot or the regex is bypassed for names where is_match returned false.

Common situations: Migrating Elasticsearch mappings that contain meta fields like `_id` or `_source`; copy-pasted ES index templates; hand-written YAML where a dash-space indent produced a leading dot.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• field name `{}` is too long. field names must not be longer
• field name `{}` is invalid. field names must start with an u
• field name `{}` contains illegal characters. field names mus
• field name is empty
• duplicated field definition `{}`

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