field name `{}` is invalid. field names must start with an u

Error message

field name `{}` is invalid. field names must start with an uppercase or lowercase ASCII letter, or an underscore `_`

What it means

Field names must begin with an ASCII letter (a-z, A-Z) or an underscore; the first character of the supplied name failed this check. Names starting with digits, hyphens, or non-ASCII characters are rejected because they are error-prone in query syntax and downstream tooling.

Source

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

    }
    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
        )
    }
    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};

View on GitHub (pinned to a39730c5cd)

Solutions

Rename the field so it starts with an ASCII letter or underscore (e.g. `count_2xx`).
Prefix numeric-derived names with an underscore or word.
Sanitize field-name generation code to prefix invalid first characters.

Example fix

// before
{"2xx_count": {"type": "u64"}}
// after
{"count_2xx": {"type": "u64"}}

Defensive patterns

Strategy: validation

Validate before calling

fn validate_field_name(name: &str) -> Result<(), String> {
    let first = name.chars().next().ok_or("empty name")?;
    if !first.is_ascii_alphabetic() && first != '_' {
        return Err(format!("field name `{name}` must start with an ASCII letter or `_`"));
    }
    Ok(())
}

Prevention

Prefix numeric-derived names (e.g. 2xx) with a word or underscore.
Sanitize identifiers sourced from external systems before creating mappings.
Write unit tests for the name generator covering digits/hyphens as first char.

When it happens

Trigger: Defining a mapping field whose first character is a digit, '-', or non-ASCII letter, e.g. `{"2xx_count": {"type": "u64"}}` or `{"-field": ...}` — the regex check failed and the first char is not ASCII alphabetic.

Common situations: Field names derived from HTTP status classes (`2xx`), metric names with leading digits, translations of keys from data sources that allow any identifier, names starting with hyphens copied from CLI flags.

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

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