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 when the supplied Pattern is null. The classic consumer requires a non-null pattern; a null pattern would otherwise cause an NPE later during periodic metadata matching. The guard sits before subscription state mutation so the consumer remains in a consistent state.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/ClassicKafkaConsumer.java:577

     * the max metadata age, the consumer will refresh metadata more often and check for matching topics.
     * <p>
     * See {@link #subscribe(Collection, ConsumerRebalanceListener)} for details on the
     * use of the {@link ConsumerRebalanceListener}. Generally rebalances are triggered when there
     * is a change to the topics matching the provided pattern and when consumer group membership changes.
     * Group rebalances only take place during an active call to {@link #poll(Duration)}.
     *
     * @param pattern Pattern to subscribe to
     * @param listener {@link Optional} listener instance to get notifications on partition assignment/revocation
     *                 for the subscribed topics
     * @throws IllegalArgumentException If pattern or listener is null
     * @throws IllegalStateException If {@code subscribe()} is called previously with topics, or assign is called
     *                               previously (without a subsequent call to {@link #unsubscribe()}), or if not
     *                               configured at-least one partition assignment strategy
     */
    private void subscribeInternal(Pattern pattern, Optional<ConsumerRebalanceListener> listener) {
        throwIfGroupIdNotDefined();
        if (pattern == null || pattern.toString().isEmpty())
            throw new IllegalArgumentException("Topic pattern to subscribe to cannot be " + (pattern == null ?
                    "null" : "empty"));

        acquireAndEnsureOpen();
        try {
            throwIfNoAssignorsConfigured();
            log.info("Subscribed to pattern: '{}'", pattern);
            this.subscriptions.subscribe(pattern, listener);
            this.coordinator.updatePatternSubscription(metadata.fetch());
            this.metadata.requestUpdateForNewTopics();
        } finally {
            release();
        }
    }

    public void unsubscribe() {
        acquireAndEnsureOpen();
        try {
            fetcher.clearBufferedDataForUnassignedPartitions(Collections.emptySet());

View on GitHub (pinned to c31c9215e1)

Solutions

1. Pass a non-null java.util.regex.Pattern, e.g. consumer.subscribe(Pattern.compile(System.getProperty("topic.filter", ".*"))).
2. Default the pattern from configuration with a fallback so it can never resolve to null.
3. Add a null check in application code before calling subscribe to surface the misconfiguration with a clearer message.

Example fix

// before
Pattern p = props.containsKey("topic.filter") ? Pattern.compile(props.getProperty("topic.filter")) : null;
consumer.subscribe(p);

// after
Pattern p = Pattern.compile(props.getProperty("topic.filter", ".*"));
consumer.subscribe(p);

// Validate pattern before subscribe
java.util.regex.Pattern pattern = /* ... */;
if (pattern == null) {
    throw new IllegalArgumentException("Topic pattern to subscribe to cannot be null");
}
consumer.subscribe(pattern);

java.util.Objects.requireNonNull(pattern, "Topic pattern to subscribe to cannot be null");

try {
    consumer.subscribe(pattern);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("null")) { /* supply a default pattern */ }
    else throw e;
}

When it happens

Trigger: Calling consumer.subscribe((Pattern) null) or consumer.subscribe(null, listener). Passing a field/variable that was never initialized and resolving to null at runtime.

Common situations: Loading a topic-filter regex from config/properties where the key is missing and defaults to null. Refactoring that introduces a code path assigning null before subscribe is reached.

Related errors

• RebalanceListener cannot be null
• Topic pattern to subscribe to cannot be null
• Topic pattern to subscribe to cannot be empty
• 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/06d6cd24611ab422.json. Report an issue: GitHub.