elastic/elasticsearch · error · IllegalArgumentException

pattern [{}] is referencing a non-existent pattern [{}]

Error message

pattern [{}] is referencing a non-existent pattern [{}]

What it means

Thrown during cycle detection when a %{NAME} reference resolves to a name that is absent from the bank. getPatternNamesForPattern extracts the name between %{ and }/: and looks it up; a null lookup means the referenced pattern was never defined, so the bank is inconsistent and matching would silently fail.

Source

Thrown at libs/grok/src/main/java/org/elasticsearch/grok/PatternBank.java:181

            int begin = i + 2;
            int bracketIndex = pattern.indexOf('}', begin);
            int columnIndex = pattern.indexOf(':', begin);
            int end;
            if (bracketIndex != -1 && columnIndex == -1) {
                end = bracketIndex;
            } else if (columnIndex != -1 && bracketIndex == -1) {
                end = columnIndex;
            } else if (bracketIndex != -1) {
                end = Math.min(bracketIndex, columnIndex);
            } else {
                throw new IllegalArgumentException("pattern [" + pattern + "] has an invalid syntax");
            }
            String otherPatternName = pattern.substring(begin, end);
            if (patternReferences.contains(otherPatternName) == false) {
                patternReferences.add(otherPatternName);
                String otherPattern = bank.get(otherPatternName);
                if (otherPattern == null) {
                    throw new IllegalArgumentException(
                        "pattern [" + patternName + "] is referencing a non-existent pattern [" + otherPatternName + "]"
                    );
                }
            }
        }
        return patternReferences.toArray(new String[0]);
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

  1. The message names both the referencing pattern and the missing name: add an entry for the missing name, or fix the reference to point at an existing name.
  2. Check for typos and case sensitivity in the referenced name (the lookup is exact Map.get).
  3. If importing a standard grok pattern set, ensure all transitively referenced patterns from that set are included, not just the top-level entry.
  4. If the reference is genuinely unused, delete the %{NAME} token from the pattern body.

Example fix

// before
Map<String,String> patterns = new HashMap<>();
patterns.put("LOG", "%{IP:ip} %{WORD:user}"); // IP and WORD undefined
new PatternBank(patterns); // throws: pattern [LOG] is referencing a non-existent pattern [IP]

// after
patterns.put("IP", "\\d{1,3}(\\.\\d{1,3}){3}");
patterns.put("WORD", "\\w+");
patterns.put("LOG", "%{IP:ip} %{WORD:user}");
new PatternBank(patterns); // ok
Defensive patterns

Strategy: validation

Validate before calling

// Verify every referenced name exists in the bank before construction.
static java.util.List<String> missingRefs(java.util.Map<String,String> patterns) {
    java.util.List<String> missing = new java.util.ArrayList<>();
    java.util.regex.Pattern ref = java.util.regex.Pattern.compile("%\\{(\\w+)");
    for (var e : patterns.entrySet()) {
        java.util.Matcher m = ref.matcher(e.getValue());
        while (m.find()) {
            if (!patterns.containsKey(m.group(1))) missing.add(e.getKey() + " -> " + m.group(1));
        }
    }
    return missing;
}

Try / catch

try {
    PatternBank bank = new PatternBank(patterns);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("referencing a non-existent pattern")) {
        // message names referencing pattern and missing name
        reportConfigError(e.getMessage());
    } else throw e;
}

Prevention

When it happens

Trigger: Constructing a PatternBank where a value references an undefined name, e.g. {"A":"%{MISSING}"} with no MISSING key. Also fires when a referenced pattern was removed from the map but a stale consumer still ships the old referencing pattern.

Common situations: Forgetting to bundle a base pattern (e.g. referencing %{IPV4} without including the stdlib IPV4 definition); renaming a pattern but not updating its callers; case mismatch (IPV4 vs ipv4); loading a subset of a pattern catalog that has external dependencies.

Related errors

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