{"record":{"id":"0c8772dc3d98ecfb","repo":"quickwit-oss/quickwit","slug":"field-name-must-not-start-with-a-dot","errorCode":null,"errorMessage":"field name `{}` must not start with a dot `.`","messagePattern":"field name `(.+?)` must not start with a dot `\\.`","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"quickwit/quickwit-doc-mapper/src/doc_mapper/field_mapping_entry.rs","lineNumber":891,"sourceCode":"pub fn validate_field_mapping_name(field_mapping_name: &str) -> anyhow::Result<()> {\n    static FIELD_MAPPING_NAME_PTN: LazyLock<Regex> =\n        LazyLock::new(|| Regex::new(FIELD_MAPPING_NAME_PATTERN).unwrap());\n\n    if QW_RESERVED_FIELD_NAMES.contains(&field_mapping_name) {\n        bail!(\n            \"field name `{field_mapping_name}` is reserved. the following fields are reserved for \\\n             Quickwit internal usage: {}\",\n            QW_RESERVED_FIELD_NAMES.join(\", \"),\n        );\n    }\n    if FIELD_MAPPING_NAME_PTN.is_match(field_mapping_name) {\n        return Ok(());\n    }\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    }","sourceCodeStart":873,"sourceCodeEnd":909,"githubUrl":"https://github.com/quickwit-oss/quickwit/blob/a39730c5cdcd1a4fe798403737ae293999ea21f8/quickwit/quickwit-doc-mapper/src/doc_mapper/field_mapping_entry.rs#L873-L909","documentation":"Quickwit forbids field names that begin with a dot. Leading dots conflict with the nested-field path notation where dots separate parent and child fields, so a name like `.foo` is ambiguous and rejected during field mapping validation.","triggerScenarios":"Defining a mapping field whose name starts with '.', e.g. `{\"._source\": {\"type\": \"json\"}}`, when calling FieldMappingEntryBuilder::default(); note names matching FIELD_MAPPING_NAME_PTN pass before this check, so the name reached the dot check via a pattern with a leading dot or the regex is bypassed for names where is_match returned false.","commonSituations":"Migrating Elasticsearch mappings that contain meta fields like `_id` or `_source`; copy-pasted ES index templates; hand-written YAML where a dash-space indent produced a leading dot.","solutions":["Remove the leading dot from the field name in the mapping.","For ES-style meta fields, rename (e.g. `_id` to `doc_id`) and configure the doc mapper accordingly.","If the field is nested, nest it properly (`parent.child`) instead of prefixing a dot."],"exampleFix":"// before\n{\"._source\": {\"type\": \"json\"}}\n// after\n{\"source\": {\"type\": \"json\"}}","handlingStrategy":"validation","validationCode":"fn validate_field_name(name: &str) -> Result<(), String> {\n    if name.starts_with('.') {\n        return Err(format!(\"field name `{name}` must not start with a dot\"));\n    }\n    Ok(())\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Strip or rename ES meta fields (`_id`, `_source`) during migration.","Sanitize generated field names to drop leading dots.","Use nested object syntax instead of dot prefixes for hierarchy."],"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"}