What causes "[{name}] failed to parse object" in elastic/elasticsearch?

Read the cause of the thrown XContentParseException; the actionable detail (which field/token/IO problem) is there, not in the wrapper message.

elastic/elasticsearch · error · XContentParseException

[{name}] failed to parse object

Error message

[{name}] failed to parse object

What it means

ConstructingObjectParser.apply wraps any IOException raised during parse() into an XContentParseException tagged with the parser's name and the token location. apply() is the BiFunction entry point used when integrating with ObjectParser pipelines. The root cause is preserved as the exception's cause, so the inner IOException (often a low-level read or sub-parse failure) is what actually went wrong.

Source

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

     *        argument is the value of the context provided to the {@link #parse(XContentParser, Object) parse function}. If any of the
     *        constructor arguments aren't defined in the XContent then parsing will throw an error. We use an array here rather than a
     *        {@code Map<String, Object>} to save on allocations.
     */
    public ConstructingObjectParser(String name, boolean ignoreUnknownFields, BiFunction<Object[], Context, Value> builder) {
        objectParser = new ObjectParser<>(name, ignoreUnknownFields, null);
        this.builder = builder;

    }

    /**
     * Call this to do the actual parsing. This implements {@link BiFunction} for conveniently integrating with ObjectParser.
     */
    @Override
    public Value apply(XContentParser parser, Context context) {
        try {
            return parse(parser, context);
        } catch (IOException e) {
            throw new XContentParseException(parser.getTokenLocation(), "[" + objectParser.getName() + "] failed to parse object", e);
        }
    }

    @Override
    public Value parse(XContentParser parser, Context context) throws IOException {
        return objectParser.parse(parser, new Target(parser, context), context).finish();
    }

    /**
     * Pass the {@linkplain BiConsumer} this returns the declare methods to declare a required constructor argument. See this class's
     * javadoc for an example. The order in which these are declared matters: it is the order that they come in the array passed to
     * {@link #builder} and the order that missing arguments are reported to the user if any are missing. When all of these parameters are
     * parsed from the {@linkplain XContentParser} the target object is immediately built.
     */
    @SuppressWarnings("unchecked") // Safe because we never call the method. This is just trickery to make the interface pretty.
    public static <Value, FieldT> BiConsumer<Value, FieldT> constructorArg() {
        return (BiConsumer<Value, FieldT>) REQUIRED_CONSTRUCTOR_ARG_MARKER;
    }

View on GitHub (pinned to db6a809a66)

Solutions

Read the cause of the thrown XContentParseException; the actionable detail (which field/token/IO problem) is there, not in the wrapper message.
Validate the input is complete and well-formed before handing it to apply(), or ensure the upstream reader cannot close mid-object.
If integrating via parse() directly is possible, call it to receive the raw IOException instead of the wrapped form, simplifying diagnostics.

Defensive patterns

Strategy: try-catch

Try / catch

try {
    Value v = parser.apply(parser, ctx);
} catch (XContentParseException e) {
    Throwable root = e.getCause(); // the real IOException
    // handle/recover based on root
}

Prevention

Prefer parse() over apply() when you can handle IOException directly, to avoid the wrapper.
Validate input completeness (Content-Length, non-null stream) before parsing.
Log the cause, not just the wrapper message, to preserve diagnostics.

When it happens

Trigger: Any IOException during parsing the object body: malformed token stream, premature EOF, a declared field's sub-parser failing, or a NamedObject lookup throwing. Calling apply(parser, context) on truncated or structurally invalid input.

Common situations: Truncated request bodies in REST handlers. Partial reads from a stream that closes mid-object. Chained parsers where an inner ObjectParser throws and the outer ConstructingObjectParser propagates it through apply().

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

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