apache/kafka · error · IllegalArgumentException

Topic pattern cannot be {null|empty}

Error message

Topic pattern cannot be {null|empty}

What it means

Thrown by MockConsumer.subscribeInternal(SubscriptionPattern, listener) when the pattern is null or its toString() is empty. The SubscriptionPattern drives topic matching, and an empty/null pattern would match nothing meaningfully and is almost always a config bug. The message tells you which of the two (null vs empty) was the case.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/MockConsumer.java:227

        subscribeInternal(pattern, listener);
    }

    @Override
    public synchronized void subscribe(SubscriptionPattern pattern) {
        subscribeInternal(pattern, null);
    }

    @Override
    public void subscribe(Collection<String> topics, final ConsumerRebalanceListener listener) {
        if (listener == null)
            throw new IllegalArgumentException("RebalanceListener cannot be null");

        subscribeInternal(topics, listener);
    }

    private synchronized void subscribeInternal(SubscriptionPattern pattern, ConsumerRebalanceListener listener) {
        if (pattern == null || pattern.toString().isEmpty())
            throw new IllegalArgumentException("Topic pattern cannot be " + (pattern == null ? "null" : "empty"));

        ensureNotClosed();
        committed.clear();
        if (listener != null)
            subscriptions.setRebalanceListener(listener, this);
        subscriptions.subscribe(pattern);
    }

    private synchronized void subscribeInternal(Collection<String> topics, ConsumerRebalanceListener listener) {
        ensureNotClosed();
        committed.clear();
        if (listener != null)
            subscriptions.setRebalanceListener(listener, this);
        subscriptions.subscribe(new HashSet<>(topics));
    }

    private synchronized void subscribeInternal(Pattern pattern, ConsumerRebalanceListener listener) {
        ensureNotClosed();

View on GitHub (pinned to 996fb4585a)

Solutions

1. Ensure the SubscriptionPattern is non-null and its toString() yields a non-empty expression before subscribing.
2. Build the SubscriptionPattern from a validated non-empty source string; fail fast at startup if the source is blank.
3. If using a custom SubscriptionPattern class, override toString() to return the underlying pattern, not an empty string.

Example fix

// before
mockConsumer.subscribe(null, listener);
// or
mockConsumer.subscribe(new MySubscriptionPattern(""), listener);

// after
SubscriptionPattern pattern = SubscriptionPattern.compile("orders-.*");
mockConsumer.subscribe(pattern, listener);

Objects.requireNonNull(pattern, "SubscriptionPattern");
if (pattern.toString() == null || pattern.toString().isEmpty())
    throw new IllegalArgumentException("SubscriptionPattern must be non-empty");
mockConsumer.subscribe(pattern, listener);

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

try {
    mockConsumer.subscribe(pattern, listener);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Topic pattern cannot be")) {
        // load a validated default pattern and retry
    }
    throw e;
}

When it happens

Trigger: Calling subscribe with a null SubscriptionPattern; passing a custom SubscriptionPattern whose toString() returns ""; constructing a SubscriptionPattern from an empty input string; refactor that drops pattern construction but keeps the subscribe call.

Common situations: Tests building SubscriptionPattern from externalized config that was unset; custom SubscriptionPattern implementations with a buggy toString; helpers that return null when no pattern is configured.

Related errors

• RebalanceListener cannot be null
• MaxPollRecords must be strictly superior to 0
• Cannot lose partitions that are not currently assigned: {not
• Cannot add records for a partition that is not assigned to t
• You can only check the position for partitions assigned to t

AI-assisted analysis of apache/kafka@996fb4585a (2026-08-11). Data as JSON: /api/errors/c4033ff33aee6a0f. Report an issue: GitHub.