quickwit-oss/quickwit · error

field name `{}` contains illegal characters. field names mus

Error message

field name `{}` contains illegal characters. field names must only contain uppercase and lowercase ASCII letters, digits, hyphens `-`, periods `.`, and underscores `_`

What it means

Field names may only contain ASCII letters, digits, '.', '-', and '_'; the supplied name contains a character outside this set. This is the final fallback check after the regex, empty, dot-prefix, length, and first-character checks all pass or fail.

Source

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

            "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
        )
    }
    bail!(
        "field name `{}` contains illegal characters. field names must only contain uppercase and \
         lowercase ASCII letters, digits, hyphens `-`, periods `.`, and underscores `_`",
        field_mapping_name
    );
}

#[cfg(test)]
mod tests {
    use anyhow::bail;
    use matches::matches;
    use serde_json::json;
    use tantivy::schema::{IndexRecordOption, JsonObjectOptions, TextOptions};

    use super::*;
    use crate::Cardinality;
    use crate::doc_mapper::{FastFieldOptions, FieldMappingType};

    #[test]

View on GitHub (pinned to a39730c5cd)

Solutions

1. Rename the field replacing illegal characters with underscores.
2. Sanitize source keys in an ingest transform before indexing.
3. For arbitrary keys, index them as JSON fields (`type: json`) instead of top-level mapping fields.

Example fix

// before
{"user name": {"type": "text"}}
// after
{"user_name": {"type": "text"}}

fn validate_field_name(name: &str) -> Result<(), String> {
    let valid = name.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '-' | '_'));
    if !valid {
        return Err(format!("field name `{name}` contains illegal characters"));
    }
    Ok(())
}

When it happens

Trigger: Defining a mapping field whose name contains spaces, slashes, '@', '#', non-ASCII characters, etc., e.g. `{"user name": {"type": "text"}}` or `{"price$": ...}` when building FieldMappingEntry.

Common situations: Mappings derived directly from raw log/JSON keys that contain spaces or symbols; CSV headers used as field names; non-ASCII field names from localized data sources.

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 `{}` must not start with a dot `.`
• field name `{}` is too long. field names must not be longer
• field name `{}` is invalid. field names must start with an u
• field name is empty
• duplicated field definition `{}`

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