apache/kafka · error · java.lang.IllegalArgumentException

Topic partition collection to assign to cannot be null

Error message

Topic partition collection to assign to cannot be null

What it means

Thrown by assign(Collection<TopicPartition>) when the partitions argument is null. Manual assignment (the non-group path) requires an explicit, non-null collection; null indicates a programming error rather than an intentional unsubscribe. The guard fires inside the acquired lock before any subscription state changes.

Source

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

        try {
            fetcher.clearBufferedDataForUnassignedPartitions(Collections.emptySet());
            if (this.coordinator != null) {
                this.coordinator.onLeavePrepare();
                this.coordinator.maybeLeaveGroup(CloseOptions.GroupMembershipOperation.DEFAULT, "the consumer unsubscribed from all topics");
            }
            this.subscriptions.unsubscribe();
            log.info("Unsubscribed all topics or patterns and assigned partitions");
        } finally {
            release();
        }
    }

    @Override
    public void assign(Collection<TopicPartition> partitions) {
        acquireAndEnsureOpen();
        try {
            if (partitions == null) {
                throw new IllegalArgumentException("Topic partition collection to assign to cannot be null");
            } else if (partitions.isEmpty()) {
                this.unsubscribe();
            } else {
                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");
                }
                fetcher.clearBufferedDataForUnassignedPartitions(partitions);

                // make sure the offsets of topic partitions the consumer is unsubscribing from
                // are committed since there will be no following rebalance
                if (coordinator != null)
                    this.coordinator.maybeAutoCommitOffsetsAsync(time.milliseconds());

                log.info("Assigned to partition(s): {}", partitions.stream().map(TopicPartition::toString).collect(Collectors.joining(", ")));
                if (this.subscriptions.assignFromUser(new HashSet<>(partitions)))
                    metadata.requestUpdateForNewTopics();

View on GitHub (pinned to c31c9215e1)

Solutions

1. Pass an explicit collection of TopicPartition objects, even if it is Collections.emptyList() (an empty list is treated as unsubscribe, not an error).
2. Return Collections.emptyList() from helper methods instead of null when no partitions are resolved.
3. Add a null check in caller code to surface the misconfiguration earlier with application context.

Example fix

// before
List<TopicPartition> parts = partitionResolver.resolve(topic); // returns null
consumer.assign(parts);

// after
List<TopicPartition> parts = partitionResolver.resolve(topic);
if (parts == null) parts = Collections.emptyList();
consumer.assign(parts);

java.util.Collection<org.apache.kafka.common.TopicPartition> partitions = /* ... */;
if (partitions == null) {
    throw new IllegalArgumentException("Topic partition collection to assign to cannot be null");
}
consumer.assign(partitions);

java.util.Objects.requireNonNull(partitions, "Topic partition collection to assign to cannot be null");

try {
    consumer.assign(partitions);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("null")) { consumer.assign(java.util.List.of()); }
    else throw e;
}

When it happens

Trigger: Calling consumer.assign(null). Passing a List<TopicPartition> field that was not populated or was set to null by a helper method.

Common situations: Refactor leaving an assignment list uninitialized. Conditional logic that returns null instead of an empty list. Tests stubbing a partition resolver that returns null.

Related errors

• Topic partitions to assign to cannot have null or empty topi
• Topic pattern to subscribe to cannot be null
• Topic partitions to assign to cannot have null or empty topi
• Partitions collection cannot be null
• Invalid negative offset

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