elastic/elasticsearch · error · XContentParseException

[{name}] failed to parse field [{field}]

Error message

[{name}] failed to parse field [{field}]

What it means

When a declared field's value is parsed, ConstructingObjectParser queues a consumer; executing that consumer can throw if the value cannot be applied (type mismatch, range error, sub-object parse failure). The catch re-wraps into XContentParseException carrying the field's saved XContentLocation and the parser name, naming the offending field. This localizes the failure to a specific field rather than the whole object.

Source

Thrown at libs/x-content/src/main/java/org/elasticsearch/xcontent/ConstructingObjectParser.java:444

    private <T> BiConsumer<Target, T> queueingConsumer(BiConsumer<Value, T> consumer, ParseField parseField) {
        return (target, v) -> {
            if (target.targetObject != null) {
                // The target has already been built. Just apply the consumer now.
                consumer.accept(target.targetObject, v);
                return;
            }
            /*
             * The target hasn't been built. Queue the consumer. The next two lines are the only allocations that ConstructingObjectParser
             * does during parsing other than the boxing the ObjectParser might do. The first one is to preserve a snapshot of the current
             * location so we can add it to the error message if parsing fails. The second one (the lambda) is the actual operation being
             * queued. Note that we don't do any of this if the target object has already been built.
             */
            XContentLocation location = target.parser.getTokenLocation();
            target.queue(targetObject -> {
                try {
                    consumer.accept(targetObject, v);
                } catch (Exception e) {
                    throw new XContentParseException(
                        location,
                        "[" + objectParser.getName() + "] failed to parse field [" + parseField.getPreferredName() + "]",
                        e
                    );
                }
            });
        };
    }

    /**
     * The target of the {@linkplain ConstructingObjectParser}. One of these is built every time you call
     * {@linkplain ConstructingObjectParser#apply(XContentParser, Object)} Note that it is not static so it inherits
     * {@linkplain ConstructingObjectParser}'s type parameters.
     */
    private class Target {
        /**
         * Array of constructor args to be passed to the {@link ConstructingObjectParser#builder}.
         */

View on GitHub (pinned to db6a809a66)

Solutions

1. Use the named field in the message to locate the offending key, then correct its value type in the request to match the declared ValueType.
2. Inspect the cause for the precise conversion failure (NumberFormatException, sub-parse error) and address that specifically.
3. If the field is legitimately polymorphic, declare it with the correct ValueType or a custom ContextParser that tolerates the shapes you send.

try {
    Value v = cop.parse(parser, ctx);
} catch (XContentParseException e) {
    if (e.getMessage().contains("failed to parse field [")) {
        String field = /* extract from message */;
        // surface field-specific error to the caller/client
    }
}

When it happens

Trigger: A declared field receives a value of the wrong type (e.g. string where a number is declared), an enum that doesn't match, an object that fails its own sub-parser, or a value that violates a constraint checked inside the BiConsumer. Field-level parsing of any declared non-constructor field that throws.

Common situations: REST API requests with a field of the wrong JSON type. Aggregation/query body parsing where a sub-object is malformed. Version mismatches where a field's accepted shape changed.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• [{name}] failed to parse object
• Required [{fields}]
• failed to build [{name}] after last required field arrived
• Failed to build [{name}] after last required field arrived
• Input does not start with Smile format header

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