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

timestamp field `{timestamp_field_path}` should be a datetim

Error message

timestamp field `{timestamp_field_path}` should be a datetime field

What it means

The timestamp field must be of `FieldMappingType::DateTime`. If `find_field_mapping_type` resolves the path but the field is any other type (text, u64, i64, etc.), the `if let` falls to the `else` branch and the DocMapper builder bails.

Source

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

        bail!("timestamp field `{timestamp_field_path}` should not start with a `.`");
    }
    if timestamp_field_path.ends_with('.') {
        bail!("timestamp field `{timestamp_field_path}` should not end with a `.`");
    }
    let Some(timestamp_field_type) =
        mapping_root_node.find_field_mapping_type(timestamp_field_path)
    else {
        bail!("could not find timestamp field `{timestamp_field_path}` in field mappings");
    };
    if let FieldMappingType::DateTime(date_time_option, cardinality) = &timestamp_field_type {
        if cardinality != &Cardinality::SingleValued {
            bail!("timestamp field `{timestamp_field_path}` should be single-valued");
        }
        if !date_time_option.fast {
            bail!("timestamp field `{timestamp_field_path}` should be a fast field");
        }
    } else {
        bail!("timestamp field `{timestamp_field_path}` should be a datetime field");
    }
    Ok(())
}

impl From<DocMapper> for DocMapperBuilder {
    fn from(default_doc_mapper: DocMapper) -> Self {
        let partition_key_str = default_doc_mapper.partition_key.to_string();
        let partition_key_opt: Option<String> = if !partition_key_str.is_empty() {
            Some(partition_key_str)
        } else {
            None
        };
        let doc_mapping = DocMapping {
            doc_mapping_uid: default_doc_mapper.doc_mapping_uid,
            mode: default_doc_mapper.mode,
            field_mappings: default_doc_mapper.field_mappings.into(),
            timestamp_field: default_doc_mapper.timestamp_field_name,
            tag_fields: default_doc_mapper.tag_field_names,

View on GitHub (pinned to a39730c5cd)

Solutions

Change the referenced field's type to `datetime` in the doc mapping.
Or add/repoint `timestamp_field` to an existing datetime field.
If the data is a numeric epoch, map the field as `datetime` with the matching `input_formats` (e.g. unix_ts_secs) instead of a plain integer type.

Example fix

// before
doc_mapping:
  field_mappings:
    - name: ts
      type: u64
  timestamp_field: "ts"
// after
doc_mapping:
  field_mappings:
    - name: ts
      type: datetime
      input_formats: [unix_ts_secs]
  timestamp_field: "ts"

Defensive patterns

Strategy: validation

Validate before calling

const f = findField(cfg.doc_mapping.field_mappings, cfg.doc_mapping.timestamp_field);
if (f && f.type !== 'datetime') throw new Error(`timestamp_field "${f.name}" must be datetime, got ${f.type}`);

Try / catch

match DocMapperBuilder::try_from(config) {
    Ok(dm) => Ok(dm),
    Err(e) if e.to_string().contains("should be a datetime field") => Err(ConfigError::InvalidTimestampField(e.to_string())),
    Err(e) => Err(e.into()),
}

Prevention

Only assign datetime-typed fields as timestamp_field.
Map epoch numbers with type: datetime and proper input_formats instead of u64/i64.
Re-check timestamp_field after any mapping type migration.

When it happens

Trigger: Calling `DocMapperBuilder::try_from` with a `timestamp_field` that resolves to a non-datetime mapped field, e.g. `type: text` or `type: u64`.

Common situations: Configuring an epoch-seconds numeric field as timestamp_field assuming integers are acceptable; a type change in the mapping (datetime → text) leaving the old timestamp_field reference; copy-pasted index configs from other systems.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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