elastic/elasticsearch · error · IllegalArgumentException

unsupported ECS compatibility mode [{}]

Error message

unsupported ECS compatibility mode [{}]

What it means

Thrown by GrokBuiltinPatterns.get(String ecsCompatibility) when the provided ECS compatibility mode string is not one of the valid modes. Valid modes are defined in ECS_COMPATIBILITY_MODES: "disabled" (legacy patterns) and "v1" (ECS v1 patterns). The get(String) overload validates the input and delegates to get(boolean) for actual loading.

Source

Thrown at libs/grok/src/main/java/org/elasticsearch/grok/GrokBuiltinPatterns.java:62

    public static synchronized PatternBank get(boolean ecsCompatibility) {
        if (ecsCompatibility) {
            if (ECS_V1_PATTERNS == null) {
                ECS_V1_PATTERNS = loadEcsPatterns();
            }
            return ECS_V1_PATTERNS;
        } else {
            if (LEGACY_PATTERNS == null) {
                LEGACY_PATTERNS = loadLegacyPatterns();
            }
            return LEGACY_PATTERNS;
        }
    }

    public static PatternBank get(String ecsCompatibility) {
        if (isValidEcsCompatibilityMode(ecsCompatibility)) {
            return get(ECS_COMPATIBILITY_V1.equals(ecsCompatibility));
        } else {
            throw new IllegalArgumentException("unsupported ECS compatibility mode [" + ecsCompatibility + "]");
        }
    }

    public static boolean isValidEcsCompatibilityMode(String ecsCompatibility) {
        return ECS_COMPATIBILITY_MODES.contains(ecsCompatibility);
    }

    private static PatternBank loadLegacyPatterns() {
        var patternNames = List.of(
            "aws",
            "bacula",
            "bind",
            "bro",
            "exim",
            "firewalls",
            "grok-patterns",
            "haproxy",
            "httpd",

View on GitHub (pinned to db6a809a66)

Solutions

1. Use one of the valid ECS compatibility modes: "disabled" or "v1".
2. If unsure, use GrokBuiltinPatterns.get(false) (boolean overload) for legacy patterns or GrokBuiltinPatterns.get(true) for ECS v1.
3. Validate the ecs_compatibility setting in the ingest pipeline configuration before passing it to GrokBuiltinPatterns.get().
4. Use GrokBuiltinPatterns.isValidEcsCompatibilityMode(value) to check before calling get().

Example fix

// before — invalid ECS mode
PatternBank bank = GrokBuiltinPatterns.get("v2");

// after — valid ECS mode
PatternBank bank = GrokBuiltinPatterns.get("v1");
// or validate first
String mode = GrokBuiltinPatterns.isValidEcsCompatibilityMode(config) ? config : "disabled";
PatternBank bank = GrokBuiltinPatterns.get(mode);

if (!GrokBuiltinPatterns.isValidEcsCompatibilityMode(ecsCompatibility)) {
    throw new IllegalArgumentException(
        "Invalid ECS compatibility mode: " + ecsCompatibility + ". Valid modes: " + GrokBuiltinPatterns.ECS_COMPATIBILITY_MODES);
}
PatternBank bank = GrokBuiltinPatterns.get(ecsCompatibility);

static boolean isValidEcsMode(String mode) {
    return GrokBuiltinPatterns.ECS_COMPATIBILITY_MODES.contains(mode);
}

When it happens

Trigger: Calling GrokBuiltinPatterns.get(ecsCompatibility) with a string other than "disabled" or "v1". This typically occurs in Elasticsearch ingest processor configuration where the ECS compatibility setting is user-provided. Passing null, "off", "true", "legacy", or any other value triggers this error.

Common situations: Elasticsearch grok ingest processor configured with an invalid ecs_compatibility setting; pipeline migration from Logstash where different ECS mode names are used; typo in configuration (e.g. "v2", "ecs", "yes"); passing null when the caller expects a default.

Related errors

• Unable to find pattern [{}] in Grok's pattern dictionary
• circular reference in pattern back [{}]
• Can not convert grok patterns to regular expression
• unsupported ECS compatibility mode [{}]
• grok pattern matching was interrupted after [{}] ms

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