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

tags collection is not allowed on `{}` fields

Error message

tags collection is not allowed on `{}` fields

What it means

Tags are only permitted on Str (with raw tokenizer), U64, and I64 fields. Other field types (bool, f64, date, bytes, json, arrays) are rejected because their multiple textual representations would cause zero-result-page bugs in tag-based filtering.

Source

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

            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.
        }
        _ => {
            // We avoid the bytes / bool / f64 types,
            // as they are generally speaking poor tags and we want to avoid
            // bugs associated to the multiplicity of their representation.
            //
            // (Tags are relying heavily on string manipulation and we want to
            // avoid a "ZRP because you searched you searched for 0.100 instead of 0.1",
            // or `myflag:1`, `myflag:True` instead of `myflag:true`.
            bail!(
                "tags collection is not allowed on `{}` fields",
                field_type.value_type().name().to_lowercase()
            )
        }
    }
    if !field_type.is_indexed() {
        bail!(
            "tag fields are required to be indexed. (`{}` is not configured as indexed)",
            tag_field_name
        )
    }
    Ok(())
}

/// Checks that a given text/json field name has a registered tokenizer.
fn validate_fields_tokenizers(
    schema: &Schema,
    tokenizer_manager: &TokenizerManager,

View on GitHub (pinned to a39730c5cd)

Solutions

  1. Change the field type to u64/i64 or a raw-tokenized text field if tag semantics are needed.
  2. Remove the field from `tag_fields` and filter with a regular query instead.
  3. For booleans, model the flag as a `raw` text or u64 field to make it taggable.

Example fix

# before
- name: is_error
  type: bool
tag_fields: [is_error]

# after
- name: is_error
  type: u64
  fast: true
tag_fields: [is_error]
Defensive patterns

Strategy: validation

Validate before calling

fn check_tag_field_types(cfg: &serde_yaml::Value) -> Result<(), String> {
    let allowed = ["text", "u64", "i64", "integer", "uint64", "int64"];
    let tags: Vec<&str> = cfg["doc_mapping"]["tag_fields"].as_sequence()
        .map(|s| s.iter().filter_map(|v| v.as_str()).collect()).unwrap_or_default();
    if let Some(fields) = cfg["doc_mapping"]["field_mappings"].as_sequence() {
        for f in fields {
            let name = f["name"].as_str().unwrap_or_default();
            let ty = f["type"].as_str().unwrap_or_default();
            if tags.contains(&name) && !allowed.contains(&ty) {
                return Err(format!("tags not allowed on `{}` fields: {name}", ty));
            }
        }
    }
    Ok(())
}

Try / catch

if let Err(e) = QuickwitDocMapper::try_from(&index_config) {
    if e.to_string().starts_with("tags collection is not allowed") {
        eprintln!("Change field type or remove from tag_fields: {e}");
    }
    return Err(e);
}

Prevention

When it happens

Trigger: `QuickwitDocMapper::try_from` where a `tag_fields` entry resolves to a field whose type is not Str/U64/I64 — e.g. bool, f64, date, bytes, or json.

Common situations: Marking a boolean flag or a timestamp/date field as a tag and hitting the representation-multiplicity restriction (e.g. `true` vs `True`, `0.1` vs `0.100`).

Related errors

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