apache/kafka · error · java.lang.IllegalArgumentException

Topic pattern to subscribe to cannot be null

Error message

Topic pattern to subscribe to cannot be null

What it means

Thrown by subscribeInternal(Pattern, Optional) when the supplied java.util.regex.Pattern is null. The branch is selected because pattern == null in the condition `pattern == null || pattern.toString().isEmpty()`. Subscribing to a null pattern is meaningless, so the client rejects it before issuing a TopicPatternSubscriptionChangeEvent.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/AsyncKafkaConsumer.java:2249

                " otherThread(id: " + currentThread.get() + ")"
            );
        refCount.incrementAndGet();
    }

    /**
     * Release the light lock protecting the consumer from multithreaded access.
     */
    private void release() {
        if (refCount.decrementAndGet() == 0)
            currentThread.set(NO_CURRENT_THREAD);
    }

    private void subscribeInternal(Pattern pattern, Optional<ConsumerRebalanceListener> listener) {
        acquireAndEnsureOpen();
        try {
            throwIfGroupIdNotDefined();
            if (pattern == null || pattern.toString().isEmpty())
                throw new IllegalArgumentException("Topic pattern to subscribe to cannot be " + (pattern == null ?
                    "null" : "empty"));
            log.info("Subscribed to pattern: '{}'", pattern);
            applicationEventHandler.addAndGet(new TopicPatternSubscriptionChangeEvent(
                pattern,
                listener,
                defaultApiTimeoutDeadlineMs()
            ));
        } finally {
            release();
        }
    }

    /**
     * Subscribe to the RE2/J pattern. This will generate an event to update the pattern in the
     * subscription state, so it's included in the next heartbeat request sent to the broker.
     * No validation of the pattern is performed by the client (other than null/empty checks).
     */
    private void subscribeToRegex(SubscriptionPattern pattern,

View on GitHub (pinned to c31c9215e1)

Solutions

1. Guard the call: if (pattern != null) consumer.subscribe(pattern); else handle missing config explicitly.
2. Default the configuration to a sensible regex (e.g. ".*") when the property is absent.
3. Fail fast at application startup if the required pattern property is missing rather than at runtime.

Example fix

// before
Pattern p = props.get("topics.pattern") != null ? Pattern.compile(props.get("topics.pattern")) : null;
consumer.subscribe(p); // throws if property missing

// after
String patternStr = props.getProperty("topics.pattern");
if (patternStr == null || patternStr.isBlank()) {
    throw new IllegalStateException("topics.pattern must be configured");
}
consumer.subscribe(Pattern.compile(patternStr));

// Before consumer.subscribe(pattern):
if (pattern == null) throw new IllegalArgumentException("pattern must not be null");
Objects.requireNonNull(pattern, "Pattern");
consumer.subscribe(pattern);

static boolean isNonNullOrEmptyPattern(Pattern p) {
    return p != null && !p.toString().isEmpty();
}

try {
    consumer.subscribe(pattern);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("cannot be null")) {
        log.warn("Null pattern supplied; skipping subscribe", e);
    } else throw e;
}

When it happens

Trigger: Calling consumer.subscribe((Pattern) null); passing a Pattern field that was never assigned; a method that builds a Pattern from config and returns null when the config is missing; conditional code that calls subscribe(pattern) where pattern may be null.

Common situations: Configuration-driven subscriptions where the regex property is optional and resolved to null; refactoring from collection-based subscribe to pattern-based subscribe; test code passing null inadvertently; environment-specific setups that omit the topic pattern property in one environment.

Related errors

• Topic pattern to subscribe to cannot be empty
• RebalanceListener cannot be null
• Topic partitions to assign to cannot have null or empty topi
• Topic collection to subscribe to cannot be null
• Topic collection to subscribe to cannot contain null or empt

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