field name `{}` is too long. field names must not be longer

Error message

field name `{}` is too long. field names must not be longer than 255 characters

What it means

Doc-mapper field name validation found a mapping entry whose field name exceeds 255 characters. Long names are rejected because they bloat tantivy field metadata and can hit internal limits; the guard runs after the reserved-name and pattern checks in field_mapping_entry.rs.

Source

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

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

View on GitHub (pinned to a39730c5cd)

Solutions

Shorten the field name to at most 255 characters/bytes.
Use nested object fields instead of one long dotted flat name.
Hash or abbreviate auto-generated long identifiers in the mapping generator.

Example fix

// before
{"a_very_long_name_".repeat(30): {"type": "text"}}
// after
{"short_name": {"type": "text"}}

Defensive patterns

Strategy: validation

Validate before calling

fn validate_field_name(name: &str) -> Result<(), String> {
    if name.len() > 255 {
        return Err(format!("field name is too long ({} bytes > 255)", name.len()));
    }
    Ok(())
}

Prevention

Cap auto-generated field name length in pipeline code.
Prefer nested fields over long dotted flat names.
Add a length assertion in mapping-generation tests.

When it happens

Trigger: Creating a FieldMappingEntry whose name exceeds 255 bytes, e.g. programmatically joining many nested path segments into a single flat name, or generating fields with long UUID-composed identifiers.

Common situations: Auto-generated mappings from log pipelines concatenating many path segments; storing raw JSON keys as flat field names; migrations from systems without a name length limit.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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