{"record":{"id":"83f86d72af8516f2","repo":"quickwit-oss/quickwit","slug":"field-name-is-invalid-field-names-must-start","errorCode":null,"errorMessage":"field name `{}` is invalid. field names must start with an uppercase or lowercase ASCII letter, or an underscore `_`","messagePattern":"field name `(.+?)` is invalid\\. field names must start with an uppercase or lowercase ASCII letter, or an underscore `_`","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"quickwit/quickwit-doc-mapper/src/doc_mapper/field_mapping_entry.rs","lineNumber":904,"sourceCode":"    }\n    if field_mapping_name.is_empty() {\n        bail!(\"field name is empty\");\n    }\n    if field_mapping_name.starts_with('.') {\n        bail!(\n            \"field name `{}` must not start with a dot `.`\",\n            field_mapping_name\n        );\n    }\n    if field_mapping_name.len() > 255 {\n        bail!(\n            \"field name `{}` is too long. field names must not be longer than 255 characters\",\n            field_mapping_name\n        )\n    }\n    let first_char = field_mapping_name.chars().next().unwrap();\n    if !first_char.is_ascii_alphabetic() {\n        bail!(\n            \"field name `{}` is invalid. field names must start with an uppercase or lowercase \\\n             ASCII letter, or an underscore `_`\",\n            field_mapping_name\n        )\n    }\n    bail!(\n        \"field name `{}` contains illegal characters. field names must only contain uppercase and \\\n         lowercase ASCII letters, digits, hyphens `-`, periods `.`, and underscores `_`\",\n        field_mapping_name\n    );\n}\n\n#[cfg(test)]\nmod tests {\n    use anyhow::bail;\n    use matches::matches;\n    use serde_json::json;\n    use tantivy::schema::{IndexRecordOption, JsonObjectOptions, TextOptions};","sourceCodeStart":886,"sourceCodeEnd":922,"githubUrl":"https://github.com/quickwit-oss/quickwit/blob/a39730c5cdcd1a4fe798403737ae293999ea21f8/quickwit/quickwit-doc-mapper/src/doc_mapper/field_mapping_entry.rs#L886-L922","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n{\"2xx_count\": {\"type\": \"u64\"}}\n// after\n{\"count_2xx\": {\"type\": \"u64\"}}","handlingStrategy":"validation","validationCode":"fn validate_field_name(name: &str) -> Result<(), String> {\n    let first = name.chars().next().ok_or(\"empty name\")?;\n    if !first.is_ascii_alphabetic() && first != '_' {\n        return Err(format!(\"field name `{name}` must start with an ASCII letter or `_`\"));\n    }\n    Ok(())\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["validation","index-config","naming"],"backgroundTag":"invalid-identifier-format","analyzedSha":"a39730c5cdcd1a4fe798403737ae293999ea21f8","analyzedAt":"2026-09-08T13:19:37.784Z","contentChangedAt":"2026-09-08T13:19:37.784Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}