quickwit-oss/quickwit · error

field name is empty

Error message

field name is empty

What it means

Quickwit rejects index mapping field names that are empty strings. Field names must match FIELD_MAPPING_NAME_PTN; an empty name cannot be addressed in queries or stored in the tantivy schema, so validation fails fast when parsing a field mapping entry.

Source

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

/// - must be different from Quickwit's reserved field mapping names `_source`, `_dynamic`,
///   `_field_presence`;
/// - must not be longer than 255 characters.
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 `_`",

View on GitHub (pinned to a39730c5cd)

Solutions

1. Give the field a non-empty name in the index config mapping section.
2. Check templating/config-generation scripts that the field name placeholder is substituted.
3. Validate the mapping JSON before calling create index (e.g. quickwit index create will fail with this error pointing at the offending entry).

Example fix

// before
{"": {"type": "text"}}
// after
{"message": {"type": "text"}}

fn validate_field_name(name: &str) -> Result<(), String> {
    if name.is_empty() {
        return Err("field name must not be empty".into());
    }
    Ok(())
}

When it happens

Trigger: Calling FieldMappingEntryBuilder::default() or deserializing a mapping JSON/YAML where a field's name key is present but its value is "" (e.g. `{"": {"type": "text"}}`), or building a FieldMappingEntry programmatically with name: String::new().

Common situations: Templated index config generation that leaves a name placeholder unfilled; YAML `"":` entries from scripting; JSON keys accidentally stripped by a config transformer; copying an example mapping and deleting the field name.

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

• object type must have at least one field mapping
• concatenate type must have at least one sub-field
• fast field is not allowed for array<bytes>
• field name `{field_mapping_name}` is reserved. the following
• field name `{}` must not start with a dot `.`

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