apache/pulsar · error · IllegalArgumentException

Unknown RegexImplementation:

Error message

Unknown RegexImplementation: 

What it means

Thrown by TopicsPatternFactory.internalCreate when the configured RegexImplementation enum value has no case in the factory switch. The factory only knows a fixed set of regex engine implementations (RE2J, JDK); anything else is rejected as an unknown implementation.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/topics/TopicsPatternFactory.java:100

        }
        switch (implementation) {
            case RE2J:
                return new RE2JTopicsPattern(inputPattern, regexWithoutTopicDomainScheme);
            case JDK:
                return new JDKTopicsPattern(inputPattern, regexWithoutTopicDomainScheme);
            case RE2J_WITH_JDK_FALLBACK:
                try {
                    return new RE2JTopicsPattern(inputPattern, regexWithoutTopicDomainScheme);
                } catch (com.google.re2j.PatternSyntaxException e) {
                    log.debug()
                            .attr("pattern", regexWithoutTopicDomainScheme)
                            .exception(e)
                            .log("Failed to compile regex pattern with RE2J, fallback to JDK");
                    // Fallback to JDK implementation if RE2J fails
                    return new JDKTopicsPattern(inputPattern, regexWithoutTopicDomainScheme);
                }
            default:
                throw new IllegalArgumentException("Unknown RegexImplementation: " + implementation);
        }
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Use a supported RegexImplementation value (JDK or RE2J) in the configuration
2. Align the Pulsar client/broker versions so the configured implementation exists in the running build
3. If extending, add a case for the new RegexImplementation in internalCreate with its TopicsPattern implementation
4. Search configuration files for stale regexImplementation values after upgrades

Example fix

// before
TopicsPatternFactory.create(topic, RegexImplementation.Auto, ...) // enum value without a switch case
// after
TopicsPatternFactory.create(topic, RegexImplementation.RE2J, ...)

if (implementation != RegexImplementation.JDK && implementation != RegexImplementation.RE2J) {
    throw new IllegalArgumentException("unsupported RegexImplementation: " + implementation);
}

try {
    pattern = TopicsPatternFactory.create(topic, impl, ...);
} catch (IllegalArgumentException e) {
    log.warn("Unknown regex impl {}, falling back to JDK", impl);
    pattern = TopicsPatternFactory.create(topic, RegexImplementation.JDK, ...);
}

When it happens

Trigger: Calling TopicsPatternFactory.create with a RegexImplementation value that internalCreate does not handle — typically after a new enum constant is added (or a custom/unknown value is passed) without updating the switch statement.

Common situations: Broker/client config specifying a regex implementation unsupported by the running Pulsar version (config from a newer or older release); a downstream fork adding an enum constant without extending the factory; typos or stale configuration migration producing an unmatched value.

Related errors

• Unsupported token endpoint auth method: ${value}
• --offloadedReadPriority parameter must be one of ${allowed}
• Unrecognized auto_failover_policy: ${policyType}
• --offloadedReadPriority parameter must be one of %s but got:
• Invalid compression type

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/5a023a9e51b83f83. Report an issue: GitHub.