{"record":{"id":"c7bf6c2d0ca46001","repo":"quickwit-oss/quickwit","slug":"field-name-contains-illegal-characters-field","errorCode":null,"errorMessage":"field name `{}` contains illegal characters. field names must only contain uppercase and lowercase ASCII letters, digits, hyphens `-`, periods `.`, and underscores `_`","messagePattern":"field name `(.+?)` contains illegal characters\\. field names must only contain uppercase and lowercase ASCII letters, digits, hyphens `-`, periods `\\.`, and underscores `_`","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"quickwit/quickwit-doc-mapper/src/doc_mapper/field_mapping_entry.rs","lineNumber":910,"sourceCode":"            \"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};\n\n    use super::*;\n    use crate::Cardinality;\n    use crate::doc_mapper::{FastFieldOptions, FieldMappingType};\n\n    #[test]","sourceCodeStart":892,"sourceCodeEnd":928,"githubUrl":"https://github.com/quickwit-oss/quickwit/blob/a39730c5cdcd1a4fe798403737ae293999ea21f8/quickwit/quickwit-doc-mapper/src/doc_mapper/field_mapping_entry.rs#L892-L928","documentation":"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.","triggerScenarios":"Defining a mapping field whose name contains spaces, slashes, '@', '#', non-ASCII characters, etc., e.g. `{\"user name\": {\"type\": \"text\"}}` or `{\"price$\": ...}` when building FieldMappingEntry.","commonSituations":"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.","solutions":["Rename the field replacing illegal characters with underscores.","Sanitize source keys in an ingest transform before indexing.","For arbitrary keys, index them as JSON fields (`type: json`) instead of top-level mapping fields."],"exampleFix":"// before\n{\"user name\": {\"type\": \"text\"}}\n// after\n{\"user_name\": {\"type\": \"text\"}}","handlingStrategy":"validation","validationCode":"fn validate_field_name(name: &str) -> Result<(), String> {\n    let valid = name.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '-' | '_'));\n    if !valid {\n        return Err(format!(\"field name `{name}` contains illegal characters\"));\n    }\n    Ok(())\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Sanitize raw log/JSON keys (spaces, symbols) into snake_case before indexing.","Keep arbitrary keys in a json-type field rather than top-level mapping fields.","Run mapping validation in CI on generated configs."],"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"}