apache/kafka · error · java.lang.IllegalArgumentException

Topic pattern to subscribe to cannot be empty

Error message

Topic pattern to subscribe to cannot be empty

What it means

Thrown by subscribeInternal when the supplied Pattern is non-null but its toString() is empty (e.g. Pattern.compile("")). An empty pattern matches every topic in the cluster, which is almost never intended and would silently overload the consumer, so the client rejects it up front.

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. Provide a meaningful regex such as Pattern.compile("^events-.*") instead of an empty string.
2. Validate configuration at startup and fail loudly when the topic filter is blank.
3. Default to an explicit catch-all pattern (".*") only if consuming every topic is genuinely intended.

Example fix

// before
String filter = config.get("topic.filter"); // resolves to ""
consumer.subscribe(Pattern.compile(filter));

// after
String filter = config.getOrDefault("topic.filter", "^events-.*");
if (filter.isEmpty()) throw new IllegalStateException("topic.filter must be set");
consumer.subscribe(Pattern.compile(filter));

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

// Compile from a non-empty source string so pattern can never be empty
String src = java.util.Objects.requireNonNull(regexSource);
if (src.isEmpty()) throw new IllegalArgumentException("topic regex source is empty");
java.util.regex.Pattern pattern = java.util.regex.Pattern.compile(src);

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

When it happens

Trigger: Calling consumer.subscribe(Pattern.compile("")) or passing a Pattern built from an empty string. Loading the regex from an env var or property that resolves to an empty string.

Common situations: Configuration placeholder left as empty string (TOPIC_FILTER=). Trailing whitespace stripped to nothing. Wrong default value in a config object.

Related errors

• Topic collection to subscribe to cannot contain null or empt
• Topic collection to subscribe to cannot contain null or empt
• Invalid value `{}` for configuration {}. The value must be e
• The configured group.id should not be an empty string or whi
• RebalanceListener cannot be null

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