elastic/elasticsearch · error · IllegalArgumentException

unsupported ECS compatibility mode [{}]

Error message

unsupported ECS compatibility mode [{}]

What it means

Thrown by GrokProcessorGetAction.prepareRequest when the ecs_compatibility query parameter is not one of the valid modes accepted by GrokBuiltinPatterns.isValidEcsCompatibilityMode. The REST handler validates the parameter before forwarding the request to the grok patterns retrieval action. IllegalArgumentException surfaced as a 400-style REST error.

Source

Thrown at modules/ingest-common/src/main/java/org/elasticsearch/ingest/common/GrokProcessorGetAction.java:174

    @ServerlessScope(Scope.PUBLIC)
    public static class RestAction extends BaseRestHandler {

        @Override
        public List<Route> routes() {
            return List.of(new Route(GET, "/_ingest/processor/grok"));
        }

        @Override
        public String getName() {
            return "ingest_processor_grok_get";
        }

        @Override
        protected RestChannelConsumer prepareRequest(RestRequest request, NodeClient client) {
            boolean sorted = request.paramAsBoolean("s", false);
            String ecsCompatibility = request.param("ecs_compatibility", GrokProcessor.DEFAULT_ECS_COMPATIBILITY_MODE);
            if (GrokBuiltinPatterns.isValidEcsCompatibilityMode(ecsCompatibility) == false) {
                throw new IllegalArgumentException("unsupported ECS compatibility mode [" + ecsCompatibility + "]");
            }
            Request grokPatternsRequest = new Request(sorted, ecsCompatibility);
            return channel -> client.executeLocally(INSTANCE, grokPatternsRequest, new RestToXContentListener<>(channel));
        }
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

1. Omit ecs_compatibility to use the default (GrokProcessor.DEFAULT_ECS_COMPATIBILITY_MODE).
2. Use one of the valid modes returned by GrokBuiltinPatterns.isValidEcsCompatibilityMode (typically 'disabled' and 'v1'/'v8' depending on version).
3. Upgrade or align client tooling to the server version's supported modes.

Example fix

# before
curl 'localhost:9200/_ingest/processor/grok?ecs_compatibility=v99'
# after
curl 'localhost:9200/_ingest/processor/grok?ecs_compatibility=v8'

String ecs = request.param("ecs_compatibility", GrokProcessor.DEFAULT_ECS_COMPATIBILITY_MODE);
if (!GrokBuiltinPatterns.isValidEcsCompatibilityMode(ecs)) {
    // reject request early with a 400 listing valid modes
}

static boolean isValidEcsMode(String s) {
    return GrokBuiltinPatterns.isValidEcsCompatibilityMode(s);
}

When it happens

Trigger: Calling GET _ingest/processor/grok with ?ecs_compatibility=bogus or an unsupported value like "disabled" or "v0".

Common situations: User typos the parameter value, follows outdated docs referencing a deprecated mode, or attempts a custom ECS mode that the version doesn't support.

Related errors

• unsupported ECS compatibility mode [{}]
• field [{}] is null, cannot process it.
• Unable to find pattern [{}] in Grok's pattern dictionary
• circular reference in pattern back [{}]
• Can not convert grok patterns to regular expression

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