What causes "tag field `{tag_field_name}` should not start with a `.`" in quickwit-oss/quickwit?

Remove the leading `.` from the tag field name.

quickwit-oss/quickwit · error · anyhow::Error

tag field `{tag_field_name}` should not start with a `.`

Error message

tag field `{tag_field_name}` should not start with a `.`

What it means

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.

Source

Thrown at quickwit/quickwit-doc-mapper/src/doc_mapper/doc_mapper_impl.rs:312

            tag_field_names,
            partition_key,
            max_num_partitions: doc_mapping.max_num_partitions,
            mode: doc_mapping.mode,
            tokenizer_entries: doc_mapping.tokenizers,
            tokenizer_manager,
        })
    }
}

/// Checks that a given field name is a valid candidate for a tag.
///
/// The conditions are:
/// - the field must be str, u64, or i64
/// - if str, the field must use the `raw` tokenizer for indexing.
/// - the field must be indexed.
fn validate_tag(tag_field_name: &str, schema: &Schema) -> Result<(), anyhow::Error> {
    if tag_field_name.starts_with('.') || tag_field_name.starts_with("\\.") {
        bail!("tag field `{tag_field_name}` should not start with a `.`");
    }
    if tag_field_name.ends_with('.') {
        bail!("tag field `{tag_field_name}` should not end with a `.`");
    }
    let field = schema
        .get_field(tag_field_name)
        .with_context(|| format!("unknown tag field: `{tag_field_name}`"))?;
    let field_type = schema.get_field_entry(field).field_type();
    match field_type {
        FieldType::Str(options) => {
            let tokenizer_opt = options
                .get_indexing_options()
                .map(|text_options: &tantivy::schema::TextFieldIndexing| text_options.tokenizer());
            if tokenizer_opt != Some(RAW_TOKENIZER_NAME) {
                bail!("tags collection is only allowed on text fields with the `raw` tokenizer");
            }
        }
        FieldType::U64(_) | FieldType::I64(_) => {

View on GitHub (pinned to a39730c5cd)

Solutions

Remove the leading `.` from the tag field name.
Reference the actual top-level field (e.g. `service` instead of `.service`).

Example fix

# before
tag_fields: [.service]

# after
tag_fields: [service]

Defensive patterns

Strategy: validation

Validate before calling

fn check_tag_names(cfg: &serde_yaml::Value) -> Result<(), String> {
    if let Some(tags) = cfg["doc_mapping"]["tag_fields"].as_sequence() {
        for t in tags {
            let name = t.as_str().unwrap_or_default();
            if name.starts_with('.') || name.starts_with("\\.") || name.ends_with('.') {
                return Err(format!("invalid tag field name: `{name}`"));
            }
        }
    }
    Ok(())
}

Try / catch

if let Err(e) = QuickwitDocMapper::try_from(&index_config) {
    if e.to_string().contains("tag field") && e.to_string().contains("`.`") {
        eprintln!("Fix tag field naming: {e}");
    }
    return Err(e);
}

Prevention

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.

When it happens

Trigger: `QuickwitDocMapper::try_from` iterating `doc_mapping.tag_fields` and calling validate_tag on a name beginning with `.` or `\.`.

Common situations: Typo or leftover path fragment like `.service` or `\..foo` when hand-editing the tag_fields list.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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