elastic/elasticsearch · error · XContentParseException

[{}] unknown field [{}]

Error message

[{}] unknown field [{}]

What it means

ObjectParser's errorOnUnknown strategy throws XContentParseException when input contains a field name not present in the parser's fieldParserMap for the active REST API version. The message lists the parser name, the offending field, and (via ErrorOnUnknown.IMPLEMENTATION) the set of known field names to guide correction. This fires only when the parser was built with ignoreUnknownFields=false.

Source

Thrown at libs/x-content/src/main/java/org/elasticsearch/xcontent/ObjectParser.java:104

    private interface UnknownFieldParser<Value, Context> {
        void acceptUnknownField(
            ObjectParser<Value, Context> objectParser,
            String field,
            XContentLocation location,
            XContentParser parser,
            Value value,
            Context context
        ) throws IOException;
    }

    private static <Value, Context> UnknownFieldParser<Value, Context> ignoreUnknown() {
        return (op, f, l, p, v, c) -> p.skipChildren();
    }

    private static <Value, Context> UnknownFieldParser<Value, Context> errorOnUnknown() {
        return (op, f, l, p, v, c) -> {
            throw new XContentParseException(
                l,
                ErrorOnUnknown.IMPLEMENTATION.errorMessage(
                    op.name,
                    f,
                    op.fieldParserMap.getOrDefault(p.getRestApiVersion(), Collections.emptyMap()).keySet()
                )
            );
        };
    }

    /**
     * Defines how to consume a parsed undefined field
     */
    public interface UnknownFieldConsumer<Value> {
        void accept(Value target, String field, Object value);
    }

    private static <Value, Context> UnknownFieldParser<Value, Context> consumeUnknownField(UnknownFieldConsumer<Value> consumer) {

View on GitHub (pinned to db6a809a66)

Solutions

1. Remove or rename the offending field; consult the known-fields list in the message.
2. If extra fields should be tolerated, construct the parser with ignoreUnknownFields=true (where semantically safe).
3. Update the parser declaration to declare the new field if it's a legitimate addition.

Example fix

// before: input has 'colour' but parser only knows 'color', ignoreUnknown=false
{"colour": "red"}

// after
{"color": "red"}

// validate request keys against the parser's declared field set before parsing
Set<String> allowed = ...; // declared field names for the active RestApiVersion
Set<String> unknown = Sets.difference(body.keySet(), allowed);
if (!unknown.isEmpty()) { /* reject with allowed list */ }

try {
    op.parse(parser, value, ctx);
} catch (XContentParseException e) {
    if (e.getMessage().contains("unknown field [")) {
        // extract field + known list, return 400 with allowed fields
    }
}

When it happens

Trigger: Submitting a request/object containing an undeclared field to an ObjectParser (or ConstructingObjectParser) created with ignoreUnknownFields=false. Typo in a field name, extra/unknown fields in a strict schema, or version skew where a field was removed/renamed.

Common situations: Strict REST endpoints that reject unknown fields. Aggregation/query parsing where an unsupported option is passed. Clients sending new fields to an older cluster, or vice versa.

Related errors

• [{}] cannot parse field [{}] with value type [{}]
• expected value but got [{token}]
• deprecated fields not supported in [{parserName}] but got [{
• deprecated fields not supported here but got [{oldName}] whi
• deprecated fields not supported in [{parserName}] but got [{

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/c1dc409e897c378f. Report an issue: GitHub.