elastic/elasticsearch · error · UnsupportedOperationException

deprecated fields not supported in [{parserName}] but got [{

Error message

deprecated fields not supported in [{parserName}] but got [{oldName}] at [{location}] which is a deprecated name for [{replacedName}]

What it means

The THROW_UNSUPPORTED_OPERATION DeprecationHandler.logReplacedField throws UnsupportedOperationException when the parser encounters a field supplied under a deprecated 'replaced' name (the field is deprecated in favor of a different field) and parserName is non-null. parserName identifies which parser's context rejected it; location pins the source position. Use this handler to fail fast on deprecated fields in strict contexts.

Source

Thrown at libs/x-content/src/main/java/org/elasticsearch/xcontent/DeprecationHandler.java:29

import java.util.function.Supplier;

/**
 * Callback for notifying the creator of the {@link XContentParser} that
 * parsing hit a deprecated field.
 */
public interface DeprecationHandler {
    /**
     * Throws an {@link UnsupportedOperationException} when parsing hits a
     * deprecated field. Use this when creating an {@link XContentParser}
     * that won't interact with deprecation logic at all or when you want
     * to fail fast when parsing deprecated fields.
     */
    DeprecationHandler THROW_UNSUPPORTED_OPERATION = new DeprecationHandler() {
        @Override
        public void logReplacedField(String parserName, Supplier<XContentLocation> location, String oldName, String replacedName) {
            if (parserName != null) {
                throw new UnsupportedOperationException(
                    "deprecated fields not supported in ["
                        + parserName
                        + "] but got ["
                        + oldName
                        + "] at ["
                        + location.get()
                        + "] which is a deprecated name for ["
                        + replacedName
                        + "]"
                );
            } else {
                throw new UnsupportedOperationException(
                    "deprecated fields not supported here but got [" + oldName + "] which is a deprecated name for [" + replacedName + "]"
                );
            }
        }

        @Override

View on GitHub (pinned to db6a809a66)

Solutions

Rename the deprecated field in the input to its replacement (replacedName in the message).
If legacy names must be tolerated, create the parser with a lenient DeprecationHandler (IGNORE_DEPRECATIONS or one that logs) instead of THROW_UNSUPPORTED_OPERATION.
Update the ParseField registration if the alias should no longer be considered deprecated.

Example fix

// before (input)
{"boost": 2.0}   // 'boost' is a deprecated alias
// with THROW_UNSUPPORTED_OPERATION handler -> error

// after
{"boost_value": 2.0}   // use the replacement name

Defensive patterns

Strategy: validation

Validate before calling

// strip or rename deprecated 'replaced' aliases before strict parsing
Map<String,Object> body = parseToMap(parserClone);
Map<String,String> replaced = Map.of("boost", "boost_value");
replaced.forEach((old, neu) -> { if (body.containsKey(old)) { body.put(neu, body.remove(old)); } });
// re-serialize and parse with THROW_UNSUPPORTED_OPERATION

Try / catch

try {
    p.parse(parser, ctx);
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("deprecated name for [")) {
        // extract replacement name and retry, or downgrade to a logging handler
    }
}

Prevention

Maintain a deprecated-alias -> replacement map at the controller and normalize input before strict parsing.
Only use THROW_UNSUPPORTED_OPERATION where legacy names must be hard-rejected; prefer logging handlers during migration windows.
Communicate field renames in release notes and SDK updates so clients stop sending old names.

When it happens

Trigger: Parsing input with DeprecationHandler.THROW_UNSUPPORTED_OPERATION where the JSON contains a field name registered as a deprecated alias that maps to a replacement field, and the parser was created with a non-null parserName. Common in internal/strict parsing paths that must reject legacy field names.

Common situations: Tightening a REST endpoint to reject pre-deprecation request shapes. Internal plugin parsing that must not accept legacy aliases. Test harnesses asserting no deprecated fields leak through.

Related errors

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