apache/kafka · error · IllegalArgumentException

Partitions collection cannot be null

Error message

Partitions collection cannot be null

What it means

Thrown by seekToBeginning(Collection<TopicPartition>) when the partitions argument is null. The operation accepts an empty collection (treated as 'all assigned partitions') but not null, since null indicates a programming error. The guard runs before acquiring the consumer lock so the failure is immediate.

Source

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

            } else {
                log.info("Seeking to offset {} for partition {}", offset, partition);
            }
            Metadata.LeaderAndEpoch currentLeaderAndEpoch = this.metadata.currentLeader(partition);
            SubscriptionState.FetchPosition newPosition = new SubscriptionState.FetchPosition(
                    offsetAndMetadata.offset(),
                    offsetAndMetadata.leaderEpoch(),
                    currentLeaderAndEpoch);
            this.updateLastSeenEpochIfNewer(partition, offsetAndMetadata);
            this.subscriptions.seekUnvalidated(partition, newPosition);
        } finally {
            release();
        }
    }

    @Override
    public void seekToBeginning(Collection<TopicPartition> partitions) {
        if (partitions == null)
            throw new IllegalArgumentException("Partitions collection cannot be null");

        acquireAndEnsureOpen();
        try {
            Collection<TopicPartition> parts = partitions.isEmpty() ? this.subscriptions.assignedPartitions() : partitions;
            subscriptions.requestOffsetReset(parts, AutoOffsetResetStrategy.EARLIEST);
        } finally {
            release();
        }
    }

    @Override
    public void seekToEnd(Collection<TopicPartition> partitions) {
        if (partitions == null)
            throw new IllegalArgumentException("Partitions collection cannot be null");

        acquireAndEnsureOpen();
        try {
            Collection<TopicPartition> parts = partitions.isEmpty() ? this.subscriptions.assignedPartitions() : partitions;

View on GitHub (pinned to c31c9215e1)

Solutions

1. Pass an explicit collection, using Collections.emptyList() to mean 'reset all assigned partitions'.
2. Make resolver helpers return Collections.emptyList() instead of null when there is nothing to reset.
3. Null-check in caller code to surface the misconfiguration with application context.

Example fix

// before
Collection<TopicPartition> toReset = partitionsToReset(); // returns null
consumer.seekToBeginning(toReset);

// after
Collection<TopicPartition> toReset = partitionsToReset();
if (toReset == null) toReset = Collections.emptyList();
consumer.seekToBeginning(toReset);

java.util.Collection<org.apache.kafka.common.TopicPartition> partitions = /* ... */;
if (partitions == null) {
    throw new IllegalArgumentException("Partitions collection cannot be null");
}
consumer.seekToBeginning(partitions); // also applies to seekToEnd

java.util.Objects.requireNonNull(partitions, "Partitions collection cannot be null");

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

When it happens

Trigger: Calling consumer.seekToBeginning(null). Passing a partition list field that was not initialized or returned null from a resolver.

Common situations: Helper that returns null instead of Collections.emptyList() when no partitions need reset. Refactor leaving a field null on a restart path. Tests stubbing partition assignment with null.

Related errors

• seek offset must not be a negative number
• Partitions collection cannot be null
• Topic pattern to subscribe to cannot be null
• Topic partition collection to assign to cannot be null
• seek offset must not be a negative number

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