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

timestamp field `{timestamp_field_path}` should not start wi

Error message

timestamp field `{timestamp_field_path}` should not start with a `.`

What it means

When building a DocMapper from its config, `validate_timestamp_field` checks the configured `timestamp_field` path. A path beginning with `.` (or the escaped form `\.`) is structurally invalid for a field path, so the builder rejects it before any indexing happens.

Source

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

    /// The partition key is a DSL used to route documents
    /// into specific splits.
    partition_key: RoutingExpr,
    /// Maximum number of partitions
    max_num_partitions: NonZeroU32,
    /// Defines how unmapped fields should be handle.
    mode: Mode,
    /// User-defined tokenizers.
    tokenizer_entries: Vec<TokenizerEntry>,
    /// Tokenizer manager.
    tokenizer_manager: TokenizerManager,
}

fn validate_timestamp_field(
    timestamp_field_path: &str,
    mapping_root_node: &MappingNode,
) -> anyhow::Result<()> {
    if timestamp_field_path.starts_with('.') || timestamp_field_path.starts_with("\\.") {
        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");

View on GitHub (pinned to a39730c5cd)

Solutions

Remove the leading `.` (and any leading `\.`) from `timestamp_field` in the index config.
Express the field as a plain dotted path from the mapping root, e.g. `timestamp_field: "timestamp"` or `"event.time"`.
Re-run index config validation after the fix.

Example fix

// before (index config YAML)
doc_mapping:
  timestamp_field: ".timestamp"
// after
doc_mapping:
  timestamp_field: "timestamp"

Defensive patterns

Strategy: validation

Validate before calling

const ts = config.doc_mapping.timestamp_field;
if (typeof ts === 'string' && (ts.startsWith('.') || ts.startsWith('\\.'))) {
  throw new Error(`timestamp_field "${ts}" must not start with a dot`);
}

Type guard

fn is_valid_leading_path(p: &str) -> bool { !p.starts_with('.') && !p.starts_with("\\.") }

Try / catch

match DocMapperBuilder::try_from(config) {
    Ok(dm) => Ok(dm),
    Err(e) if e.to_string().contains("should not start with") => Err(ConfigError::InvalidTimestampField(e.to_string())),
    Err(e) => Err(e.into()),
}

Prevention

Write timestamp_field as a plain dotted path from the mapping root.
Lint index configs for leading/trailing dots in field paths.
Generate field paths with a joiner that never adds leading separators.

When it happens

Trigger: Calling `DocMapperBuilder::try_from` (index creation or config validation) with `doc_mapping.timestamp_field` set to a value like `.timestamp` or `\.timestamp`.

Common situations: Hand-written index configs where the user typed a leading dot thinking it meant root; generated configs joining path segments with separators; YAML mistakes adding a stray dot.

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