quickwit-oss/quickwit · error

concatenate field uses an unknown field `{sub_field}`

Error message

concatenate field uses an unknown field `{sub_field}`

What it means

A `concatenate` (concatenate_fields) mapping option references a sub-field by path, and the mapping tree must resolve that path to at least one existing field mapping leaf. When `find_field_mapping_leaf` returns nothing for the referenced path, building the mapping tree fails with this message naming the unknown sub-field.

Source

Thrown at quickwit/quickwit-doc-mapper/src/doc_mapper/mapping_tree.rs:1056

        }
    }
    for concatenate_field_entry in concatenate_fields {
        let FieldMappingType::Concatenate(options) = &concatenate_field_entry.mapping_type else {
            // we only pushed Concatenate fields in `concatenate_fields`
            unreachable!();
        };
        let name = &concatenate_field_entry.name;
        if mapping_node.branches.contains_key(name) {
            bail!("duplicated field definition `{}`", name);
        }
        let text_options: JsonObjectOptions = options.clone().into();
        let field = schema.add_json_field(name, text_options);
        for sub_field in &options.concatenate_fields {
            for matched_field in
                mapping_node
                    .find_field_mapping_leaf(sub_field)
                    .ok_or_else(|| {
                        anyhow::anyhow!("concatenate field uses an unknown field `{sub_field}`")
                    })?
            {
                if !matched_field.typ.supported_for_concat() {
                    bail!(
                        "subfield `{}` not supported inside a concatenate field",
                        sub_field
                    );
                }
                matched_field.concatenate.push(field);
            }
        }
        if options.include_dynamic_fields {
            concatenate_dynamic_fields.push(field);
        }
    }
    Ok(MappingNodeRoot {
        field_mappings: mapping_node,
        concatenate_dynamic_fields,

View on GitHub (pinned to a39730c5cd)

Solutions

  1. Ensure every path listed in `concatenate_fields` exists in the index mapping with exactly the same name.
  2. Fix typos or incorrect nesting in the dotted field path.
  3. If the field was removed intentionally, delete its entry from the concatenate field's `concatenate_fields` list.
  4. Only concatenate fields whose types are supported (`supported_for_concat`) to avoid the related 'not supported' error.

Example fix

# before
concatenate_fields: [message, body_txt]
# after
concatenate_fields: [message, body_text]
Defensive patterns

Strategy: validation

Validate before calling

const concat_fields = ["message", "body_text"];
const mapped = new Set(Object.keys(indexConfig.docMapping.fieldEntries));
const missing = concat_fields.filter(f => !mapped.has(f));
if (missing.length) throw new Error(`concatenate_fields unknown: ${missing}`);

Try / catch

try {
    createIndex(cfg);
} catch (e) {
    if (String(e).includes("concatenate field uses an unknown field")) {
        // reconcile concatenate_fields with actual mapping
    }
}

Prevention

When it happens

Trigger: Declaring a concatenate field whose `concatenate_fields` list names a path that is not present in the index mapping (typo, renamed field, nested path written incorrectly), encountered during `build_mapping_tree_from_entries` when the schema/mapping is built.

Common situations: Renaming or deleting a field in the mapping while forgetting to update the concatenate field's reference list, typos in dotted nested paths, or referencing a field defined only in a different mapping version.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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