{"record":{"id":"611575e6332c66b3","repo":"quickwit-oss/quickwit","slug":"tag-field-tag-field-name-should-not-start-with","errorCode":null,"errorMessage":"tag field `{tag_field_name}` should not start with a `.`","messagePattern":"tag field `(.+?)` should not start with a `\\.`","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"quickwit/quickwit-doc-mapper/src/doc_mapper/doc_mapper_impl.rs","lineNumber":312,"sourceCode":"            tag_field_names,\n            partition_key,\n            max_num_partitions: doc_mapping.max_num_partitions,\n            mode: doc_mapping.mode,\n            tokenizer_entries: doc_mapping.tokenizers,\n            tokenizer_manager,\n        })\n    }\n}\n\n/// Checks that a given field name is a valid candidate for a tag.\n///\n/// The conditions are:\n/// - the field must be str, u64, or i64\n/// - if str, the field must use the `raw` tokenizer for indexing.\n/// - the field must be indexed.\nfn validate_tag(tag_field_name: &str, schema: &Schema) -> Result<(), anyhow::Error> {\n    if tag_field_name.starts_with('.') || tag_field_name.starts_with(\"\\\\.\") {\n        bail!(\"tag field `{tag_field_name}` should not start with a `.`\");\n    }\n    if tag_field_name.ends_with('.') {\n        bail!(\"tag field `{tag_field_name}` should not end with a `.`\");\n    }\n    let field = schema\n        .get_field(tag_field_name)\n        .with_context(|| format!(\"unknown tag field: `{tag_field_name}`\"))?;\n    let field_type = schema.get_field_entry(field).field_type();\n    match field_type {\n        FieldType::Str(options) => {\n            let tokenizer_opt = options\n                .get_indexing_options()\n                .map(|text_options: &tantivy::schema::TextFieldIndexing| text_options.tokenizer());\n            if tokenizer_opt != Some(RAW_TOKENIZER_NAME) {\n                bail!(\"tags collection is only allowed on text fields with the `raw` tokenizer\");\n            }\n        }\n        FieldType::U64(_) | FieldType::I64(_) => {","sourceCodeStart":294,"sourceCodeEnd":330,"githubUrl":"https://github.com/quickwit-oss/quickwit/blob/a39730c5cdcd1a4fe798403737ae293999ea21f8/quickwit/quickwit-doc-mapper/src/doc_mapper/doc_mapper_impl.rs#L294-L330","documentation":"validate_tag enforces that tag field names are clean dotted paths. A tag name starting with `.` (or the escaped `\\.` form) is rejected because tags are used as string keys in metadata and such leading dots break tag filtering/wildcard semantics.","triggerScenarios":"`QuickwitDocMapper::try_from` iterating `doc_mapping.tag_fields` and calling validate_tag on a name beginning with `.` or `\\.`.","commonSituations":"Typo or leftover path fragment like `.service` or `\\..foo` when hand-editing the tag_fields list.","solutions":["Remove the leading `.` from the tag field name.","Reference the actual top-level field (e.g. `service` instead of `.service`)."],"exampleFix":"# before\ntag_fields: [.service]\n\n# after\ntag_fields: [service]","handlingStrategy":"validation","validationCode":"fn check_tag_names(cfg: &serde_yaml::Value) -> Result<(), String> {\n    if let Some(tags) = cfg[\"doc_mapping\"][\"tag_fields\"].as_sequence() {\n        for t in tags {\n            let name = t.as_str().unwrap_or_default();\n            if name.starts_with('.') || name.starts_with(\"\\\\.\") || name.ends_with('.') {\n                return Err(format!(\"invalid tag field name: `{name}`\"));\n            }\n        }\n    }\n    Ok(())\n}","typeGuard":null,"tryCatchPattern":"if let Err(e) = QuickwitDocMapper::try_from(&index_config) {\n    if e.to_string().contains(\"tag field\") && e.to_string().contains(\"`.`\") {\n        eprintln!(\"Fix tag field naming: {e}\");\n    }\n    return Err(e);\n}","preventionTips":["Tag names must be plain dotted paths with no leading/trailing dots.","Validate tag_fields entries with a regex like `^[^.].*[^.]$` in CI.","Avoid manual string building of field paths for tags."],"tags":["config","tag-fields","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"}