apache/kafka · error · ConfigException

JMX filter for configuration{metricsConfigPrefix}.(include/e

Error message

JMX filter for configuration{metricsConfigPrefix}.(include/exclude) is not a valid regular expression

What it means

Thrown by JmxReporter.compilePredicate when either the metrics include or exclude filter string fails to compile as a java.util.regex.Pattern. Kafka exposes metrics through JMX optionally filtered by two regex configs (prefixed with metrics.<prefix>.include / .exclude); both must be valid regular expressions. The raw PatternSyntaxException is wrapped and rethrown as a ConfigException so the failure surfaces clearly at client/broker startup.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/metrics/JmxReporter.java:316

        String include = (String) configs.get(INCLUDE_CONFIG);
        String exclude = (String) configs.get(EXCLUDE_CONFIG);

        if (include == null) {
            include = DEFAULT_INCLUDE;
        }

        if (exclude == null) {
            exclude = DEFAULT_EXCLUDE;
        }

        try {
            Pattern includePattern = Pattern.compile(include);
            Pattern excludePattern = Pattern.compile(exclude);

            return s -> includePattern.matcher(s).matches()
                        && !excludePattern.matcher(s).matches();
        } catch (PatternSyntaxException e) {
            throw new ConfigException("JMX filter for configuration" + METRICS_CONFIG_PREFIX
                                      + ".(include/exclude) is not a valid regular expression");
        }
    }

    @Override
    public void contextChange(MetricsContext metricsContext) {
        String namespace = metricsContext.contextLabels().get(MetricsContext.NAMESPACE);
        Objects.requireNonNull(namespace);
        synchronized (LOCK) {
            if (!mbeans.isEmpty()) {
                throw new IllegalStateException("JMX MetricsContext can only be updated before JMX metrics are created");
            }

            // prevent prefix from getting reset back to empty for backwards compatibility
            // with the deprecated JmxReporter(String prefix) constructor, in case contextChange gets called
            // via one of the Metrics() constructor with a default empty MetricsContext()
            if (namespace.isEmpty()) {
                return;

View on GitHub (pinned to c31c9215e1)

Solutions

Locate the metrics.<prefix>.include and metrics.<prefix>.exclude config keys in the affected client/broker properties.
Validate each value with a quick java.util.regex.Pattern.compile check in a REPL/JUnit before redeploying.
Correct the regex (escape metacharacters with backslash, balance character classes, fix quantifiers) or replace it with a simpler literal-prefix filter.
Restart the client/broker and confirm metrics publish to JMX without the ConfigException.

Example fix

// before: metrics.include=record(.+   // unterminated group, illegal regex
// after:  metrics.include=record.+

Defensive patterns

Strategy: validation

Validate before calling

// Validate include/exclude regex BEFORE building configs consumed by JmxReporter.
String include = (String) configs.getOrDefault(JmxReporter.METRICS_CONFIG_PREFIX + ".include", JmxReporter.DEFAULT_INCLUDE);
String exclude = (String) configs.getOrDefault(JmxReporter.METRICS_CONFIG_PREFIX + ".exclude", JmxReporter.DEFAULT_EXCLUDE);
for (String re : new String[]{include, exclude}) {
    try { Pattern.compile(re); }
    catch (PatternSyntaxException e) {
        throw new IllegalArgumentException("Invalid JMX metrics regex: " + re, e);
    }
}

Type guard

// Type/narrowing helper: confirm a candidate value is a compilable regex.
boolean isValidRegex(String s) {
    if (s == null) return false;
    try { Pattern.compile(s); return true; } catch (PatternSyntaxException e) { return false; }
}

Try / catch

try {
    Predicate<String> p = JmxReporter.compilePredicate(configs);
} catch (ConfigException e) {
    // fall back to defaults or fail config loading with a clear user message
    configs.remove(JmxReporter.METRICS_CONFIG_PREFIX + ".include");
    configs.remove(JmxReporter.METRICS_CONFIG_PREFIX + ".exclude");
}

Prevention

Treat metrics.include/exclude as user-supplied config; never trust raw input.
Test regex with Pattern.compile in your config validation layer before passing to Kafka.
Use anchored, simple regexes; avoid backtracking patterns that compile but perform poorly.
Provide a config UI that surfaces PatternSyntaxException at setting time.

When it happens

Trigger: Client or broker config sets a property under the METRICS_CONFIG_PREFIX whose key ends in .include or .exclude to a malformed regex (unbalanced brackets, dangling metacharacter, invalid quantifier). Pattern.compile throws PatternSyntaxException inside compilePredicate; the catch block at JmxReporter.java:315-318 rethrows ConfigException.

Common situations: Migrating a metrics filter between regex dialects (e.g. copying a Python re pattern into the Kafka config). Typing a glob like "kafka.*" with characters that are regex metacharacters. Inadvertently setting include/exclude via environment variable substitution that yields an empty or partial token. Mixing YAML/properties escaping that strips a closing bracket.

Related errors

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/c4b57e83a74656f9.json. Report an issue: GitHub.