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

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

Error message

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

What it means

Doc-mapper validation (`validate_tag`, called when building the mapper) found a tag field whose name terminates with a dot. Trailing dots create ambiguity with Quickwit's dotted nested-field path syntax and would produce invalid pruned tags, so the name is rejected.

Source

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

            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(_) => {
            // u64 and i64 are accepted as tags.
        }
        _ => {

View on GitHub (pinned to a39730c5cd)

Solutions

  1. Strip the trailing `.` from the tag field name in the config.

Example fix

# before
tag_fields: [service.]

# after
tag_fields: [service]
Defensive patterns

Strategy: validation

Validate before calling

fn check_tag_trailing_dot(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.ends_with('.') {
                return Err(format!("tag field `{name}` ends with a dot"));
            }
        }
    }
    Ok(())
}

Try / catch

if let Err(e) = QuickwitDocMapper::try_from(&index_config) {
    if e.to_string().contains("should not end with") {
        eprintln!("Strip trailing dot from tag field: {e}");
    }
    return Err(e);
}

Prevention

When it happens

Trigger: `QuickwitDocMapper::try_from` validating a `doc_mapping.tag_fields` entry that ends with `.`.

Common situations: Trailing punctuation left from copy-paste or from joining a path with dots manually.

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/f114b99436bfbf88. Report an issue: GitHub.