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

Inspect the cause exception for the specific field-level error type and message.

elastic/elasticsearch · error · XContentParseException

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

Error message

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

What it means

Thrown by throwFailedToParse when the FieldParser's parse callback throws any Exception while consuming a field's value. This is a general-purpose wrapper that adds location (token location) and field-name context to whatever underlying parsing error occurred, making it easier to identify which field caused the failure.

Source

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

        }
        this.exclusiveFieldSets.add(exclusiveSet);
    }

    private void parseArray(XContentParser parser, FieldParser fieldParser, String currentFieldName, Value value, Context context) {
        assert parser.currentToken() == XContentParser.Token.START_ARRAY : "Token was: " + parser.currentToken();
        parseValue(parser, fieldParser, currentFieldName, value, context);
    }

    private void parseValue(XContentParser parser, FieldParser fieldParser, String currentFieldName, Value value, Context context) {
        try {
            fieldParser.parser.parse(parser, value, context);
        } catch (Exception ex) {
            throwFailedToParse(parser, currentFieldName, ex);
        }
    }

    private void throwFailedToParse(XContentParser parser, String currentFieldName, Exception ex) {
        throw new XContentParseException(parser.getTokenLocation(), "[" + name + "] failed to parse field [" + currentFieldName + "]", ex);
    }

    private void parseSub(
        XContentParser parser,
        FieldParser fieldParser,
        XContentParser.Token token,
        String currentFieldName,
        Value value,
        Context context
    ) {
        switch (token) {
            case START_OBJECT -> {
                parseValue(parser, fieldParser, currentFieldName, value, context);
                /*
                 * Well behaving parsers should consume the entire object but
                 * asserting that they do that is not something we can do
                 * efficiently here. Instead we can check that they end on an
                 * END_OBJECT. They could end on the *wrong* end object and

View on GitHub (pinned to db6a809a66)

Solutions

Inspect the cause exception for the specific field-level error type and message.
Verify the field value matches the expected type declared in the mapping or API spec.
If the cause is a number/date/format error, apply the fix for that specific underlying error.
Check the field name in the error message to locate the problematic key in the request.

Defensive patterns

Strategy: try-catch

Validate before calling

// Before sending, validate each field value type against the expected schema
Map<String, Class<?>> schema = Map.of("size", Integer.class, "name", String.class);
for (Map.Entry<String, Object> entry : body.entrySet()) {
    Class<?> expected = schema.get(entry.getKey());
    if (expected != null && !expected.isInstance(entry.getValue())) {
        throw new IllegalArgumentException(entry.getKey() + " expects " + expected.getSimpleName());
    }
}

Try / catch

try {
    objectParser.parse(parser, context);
} catch (XContentParseException e) {
    if (e.getMessage().contains("failed to parse field")) {
        String fieldName = extractFieldName(e.getMessage());
        logger.warn("Field [{}] failed to parse: {}", fieldName, e.getCause().getMessage());
        return badRequest("Invalid value for field: " + fieldName);
    }
    throw e;
}

Prevention

Validate field value types against the mapping schema before sending.
Use typed client DTOs that enforce correct field types at compile time.
Inspect the cause exception chain for the specific field-level error type.
Write unit tests that send intentionally wrong types to verify error messages.

When it happens

Trigger: Any field-level parsing failure: a number field receiving a non-numeric string, an enum field receiving an unrecognized constant, a nested object field receiving malformed sub-object content, a date field with an unparseable format string, etc. The original exception is preserved as the cause.

Common situations: Providing the wrong data type for a declared field. Sending a date in a format not matching the declared format pattern. Sending a string where a number is expected (with coercion disabled). Nesting errors in sub-objects that propagate up.

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