apache/kafka · error · java.lang.IllegalArgumentException

Topic partitions collection to assign to cannot be null

Error message

Topic partitions collection to assign to cannot be null

What it means

IllegalArgumentException from assign(Collection<TopicPartition>) when the argument is null. assign is the manual-assignment entry point; null is treated as a programmer error rather than an unsubscribe signal (pass an empty collection to unsubscribe). The guard runs after acquireAndEnsureOpen, so a closed consumer would already have thrown, and before any fetch-buffer mutation.

Source

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

     * been made.
     * @return The set of topics currently subscribed to
     */
    @Override
    public Set<String> subscription() {
        acquireAndEnsureOpen();
        try {
            return Set.copyOf(subscriptions.subscription());
        } finally {
            release();
        }
    }

    @Override
    public void assign(Collection<TopicPartition> partitions) {
        acquireAndEnsureOpen();
        try {
            if (partitions == null) {
                throw new IllegalArgumentException("Topic partitions collection to assign to cannot be null");
            }

            if (partitions.isEmpty()) {
                unsubscribe();
                return;
            }

            for (TopicPartition tp : partitions) {
                String topic = (tp != null) ? tp.topic() : null;
                if (isBlank(topic))
                    throw new IllegalArgumentException("Topic partitions to assign to cannot have null or empty topic");
            }

            // Clear the buffered data which are not a part of newly assigned topics
            final Set<TopicPartition> currentTopicPartitions = new HashSet<>();

            for (TopicPartition tp : subscriptions.assignedPartitions()) {
                if (partitions.contains(tp))

View on GitHub (pinned to c31c9215e1)

Solutions

1. Pass a non-null Collection<TopicPartition>; use Collections.emptySet() (or assign(Collections.emptyList())) if you intend to unsubscribe.
2. Fix upstream: ensure the collection is built via stream().collect() rather than assigned from a possibly-null source.
3. Add a null check before assign() to fail with a clearer application-level message if that is more useful than the library's.

Example fix

// before
Collection<TopicPartition> tps = computePartitions(); // may return null
consumer.assign(tps); // throws if null

// after
Collection<TopicPartition> tps = computePartitions();
consumer.assign(tps == null ? Collections.emptyList() : tps);

if (partitions == null) {
    throw new IllegalArgumentException("partitions must not be null");
}
consumer.assign(partitions);

Collection<TopicPartition> requireNonNullPartitions(Collection<TopicPartition> partitions) {
    return java.util.Objects.requireNonNull(partitions, "Topic partitions collection to assign to cannot be null");
}

When it happens

Trigger: Calling consumer.assign(null); also reachable via wrappers/frameworks that forward a nullable collection without checking, or by passing the result of a stream/mapping operation that yielded null (rare but possible with custom collectors).

Common situations: Static-analysis refactors that produced null sentinels; reflective/generic code that wraps assign() with an Object[]; Kotlin/Java interop where a nullable List<TopicPartition>? is forwarded unguarded; misreading the API contract where empty list means unsubscribe but null is treated as an error.

Related errors

• The target time for partition {} is {}. The target time cann
• The timeout cannot be negative.
• Topic collection to subscribe to cannot be null
• Topic collection to subscribe to cannot contain null or empt
• The configured group.id should not be an empty string or whi

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