elastic/elasticsearch · error · IllegalArgumentException

circular reference in pattern back [{}]

Error message

circular reference in pattern back [{}]

What it means

Thrown by Grok.toRegex() when a resolved pattern definition contains a self-reference — i.e., the pattern named PATTERN_NAME, when looked up from the bank, contains the text %{PATTERN_NAME} or %{PATTERN_NAME:. This would cause infinite recursion during pattern expansion, so it is detected and rejected.

Source

Thrown at libs/grok/src/main/java/org/elasticsearch/grok/Grok.java:151

            }
            handleInterrupted(result);
            if (result < 0) {
                return res.append(grokPattern).toString();
            }

            Region region = matcher.getEagerRegion();
            String namedPatternRef = groupMatch(NAME_GROUP, region, grokPattern);
            String subName = groupMatch(SUBNAME_GROUP, region, grokPattern);
            // TODO(tal): Support definitions
            @SuppressWarnings("unused")
            String definition = groupMatch(DEFINITION_GROUP, region, grokPattern);
            String patternName = groupMatch(PATTERN_GROUP, region, grokPattern);
            String pattern = patternBank.get(patternName);
            if (pattern == null) {
                throw new IllegalArgumentException("Unable to find pattern [" + patternName + "] in Grok's pattern dictionary");
            }
            if (pattern.contains("%{" + patternName + "}") || pattern.contains("%{" + patternName + ":")) {
                throw new IllegalArgumentException("circular reference in pattern back [" + patternName + "]");
            }
            String grokPart;
            if (namedCaptures && subName != null) {
                grokPart = String.format(Locale.US, "(?<%s>%s)", namedPatternRef, pattern);
            } else if (namedCaptures) {
                grokPart = String.format(Locale.US, "(?:%s)", pattern);
            } else {
                grokPart = String.format(Locale.US, "(?<%s>%s)", patternName + "_" + result, pattern);
            }
            String start = new String(grokPatternBytes, 0, result, StandardCharsets.UTF_8);
            String rest = new String(
                grokPatternBytes,
                region.getEnd(0),
                grokPatternBytes.length - region.getEnd(0),
                StandardCharsets.UTF_8
            );
            grokPattern = grokPart + rest;
            res.append(start);

View on GitHub (pinned to db6a809a66)

Solutions

1. Fix the circular reference in the pattern definition — a pattern must not reference itself directly.
2. If indirect circular references (A references B references A) exist, the MAX_TO_REGEX_ITERATIONS limit (error 616) will catch them instead; break the cycle by renaming or restructuring.
3. Validate custom patterns before registering them in the PatternBank.

Example fix

// before — circular reference
// pattern file: FOO %{FOO} extra

// after — no self-reference
// pattern file: FOO \d+ extra

// Check for direct self-references before registering a pattern
for (Map.Entry<String, String> entry : customPatterns.entrySet()) {
    String name = entry.getKey();
    String def = entry.getValue();
    if (def.contains("%{" + name + "}") || def.contains("%{" + name + ":")) {
        throw new IllegalArgumentException("Pattern '" + name + "' contains a circular self-reference");
    }
}

try {
    new Grok(bank, pattern, callback);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("circular reference")) {
        // fix the pattern definition that references itself
    }
    throw e;
}

When it happens

Trigger: Defining a pattern in the PatternBank where the pattern's value references itself. For example, registering pattern 'FOO' with value '%{FOO} bar' or '%{FOO:subname} bar'. The toRegex() method detects this when it resolves %{FOO} and finds that the expansion of FOO contains another %{FOO} reference.

Common situations: User-defined grok pattern with a typo creating a circular reference; copy-paste error when defining custom patterns in the grok ingest processor; importing patterns from another source that has circular definitions.

Related errors

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

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