field name `{field_mapping_name}` is reserved. the following

Error message

field name `{field_mapping_name}` is reserved. the following fields are reserved for Quickwit internal usage: {}

What it means

Quickwit reserves certain field names (e.g. `_source`, `_id`, `_timestamp`, `_partition`, `_tag` — QW_RESERVED_FIELD_NAMES) for internal metadata. validate_field_mapping_name rejects any mapping field whose name matches one of them, listing the reserved names in the message.

Source

Thrown at quickwit/quickwit-doc-mapper/src/doc_mapper/field_mapping_entry.rs:878

/// Regular expression validating a field mapping name.
pub const FIELD_MAPPING_NAME_PATTERN: &str = r"^[@$_\-a-zA-Z][@$_/\.\-a-zA-Z0-9]{0,254}$";

/// Validates a field mapping name.
/// Returns `Ok(())` if the name can be used for a field mapping.
///
/// A field mapping name:
/// - can only contain uppercase and lowercase ASCII letters `[a-zA-Z]`, digits `[0-9]`, `.`,
///   hyphens `-`, underscores `_`, at `@` and dollar `$` signs;
/// - must not start with a dot or a digit;
/// - must be different from Quickwit's reserved field mapping names `_source`, `_dynamic`,
///   `_field_presence`;
/// - must not be longer than 255 characters.
pub fn validate_field_mapping_name(field_mapping_name: &str) -> anyhow::Result<()> {
    static FIELD_MAPPING_NAME_PTN: LazyLock<Regex> =
        LazyLock::new(|| Regex::new(FIELD_MAPPING_NAME_PATTERN).unwrap());

    if QW_RESERVED_FIELD_NAMES.contains(&field_mapping_name) {
        bail!(
            "field name `{field_mapping_name}` is reserved. the following fields are reserved for \
             Quickwit internal usage: {}",
            QW_RESERVED_FIELD_NAMES.join(", "),
        );
    }
    if FIELD_MAPPING_NAME_PTN.is_match(field_mapping_name) {
        return Ok(());
    }
    if field_mapping_name.is_empty() {
        bail!("field name is empty");
    }
    if field_mapping_name.starts_with('.') {
        bail!(
            "field name `{}` must not start with a dot `.`",
            field_mapping_name
        );
    }
    if field_mapping_name.len() > 255 {

View on GitHub (pinned to a39730c5cd)

Solutions

Rename the field to a non-reserved name (e.g. `_id` -> `doc_id`).
If you need the document id/timestamp semantics, use Quickwit's native indexing options (`indexing_settings.timestamp_field`, node id or document `_id` handling) instead of a mapping field.
Sanitize generated mappings against QW_RESERVED_FIELD_NAMES before submitting.

Example fix

// before
{name: "_timestamp", type: "datetime", fast: true}
// after
{name: "event_time", type: "datetime", fast: true}
// plus indexing_settings.timestamp_field = event_time

Defensive patterns

Strategy: validation

Validate before calling

const RESERVED: &[&str] = &["_source", "_id", "_timestamp", "_partition", "_tag"];
fn field_name_allowed(name: &str) -> bool {
    !RESERVED.contains(&name)
}

Try / catch

match create_index_result {
    Err(e) if e.to_string().contains("is reserved") => {
        eprintln!("Rename the field; reserved names: _source, _id, _timestamp, _partition, _tag");
    }
    other => other?,
}

Prevention

Prefix user-defined metadata fields (e.g. `user_id` instead of `_id`).
Sanitize ES-style mappings before import, renaming reserved keys.
Keep the reserved-name list next to your mapping generator and check it on every emit.

When it happens

Trigger: Creating an index or adding a field mapping named exactly one of the reserved identifiers, e.g. `{name: "_source", type: "text"}` — FieldMappingEntry::try_from calls validate_field_mapping_name and bails.

Common situations: Migrating Elasticsearch mappings where `_source`-style fields existed; users trying to store their own `_id`/`_timestamp` fields; programmatic mapping generation that echoes input document keys.

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