apache/kafka · error · IllegalArgumentException

The TopicCollection: provided did not match any supported…

Error message

The TopicCollection: {topics} provided did not match any supported classes for describeTopics.

What it means

An IllegalArgumentException thrown by KafkaAdminClient.describeTopics(TopicCollection, ...) when the TopicCollection subclass is neither TopicIdCollection nor TopicNameCollection. Identical shape to the deleteTopics guard: only the two built-in subclasses are accepted.

Solutions

1. Build the collection with TopicCollection.ofTopicNames(...) or TopicCollection.ofTopicIds(...).
2. Guarantee the argument is non-null and one of the two supported concrete subclasses.
3. Unwrap any custom wrapper to a supported type before the call.

Example fix

// before
admin.describeTopics(customCollection, opts);

// after
admin.describeTopics(TopicCollection.ofTopicIds(List.of(Uuid.fromUuidString("..."))), opts);

TopicCollection topics = (ids != null && !ids.isEmpty())
    ? TopicCollection.ofTopicIds(ids)
    : TopicCollection.ofTopicNames(names);
admin.describeTopics(topics, options);

static boolean isSupportedTopicCollection(TopicCollection c) {
    return c instanceof TopicIdCollection || c instanceof TopicNameCollection;
}

When it happens

Trigger: Passing a custom TopicCollection subclass or null to admin.describeTopics(...). Subclassing TopicCollection and passing the subclass.

Common situations: Wrapper libraries that introduce their own TopicCollection type; null values from optional chaining; refactoring that left an outdated collection type in place.

Related errors

• The TopicCollection: provided did not match any supported…
• Offsets from multiple consumer groups were requested. Use…
• Cannot request fenced brokers from controller endpoint
• Cannot specify a negative version level.
• Expected minVersionLevel >= 0, maxVersionLevel >= 0 and…

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

Appendix: source

Thrown at clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java:2251

                topicListingFuture.complete(topicListing);
            }

            @Override
            void handleFailure(Throwable throwable) {
                topicListingFuture.completeExceptionally(throwable);
            }
        }, now);
        return new ListTopicsResult(topicListingFuture);
    }

    @Override
    public DescribeTopicsResult describeTopics(final TopicCollection topics, DescribeTopicsOptions options) {
        if (topics instanceof TopicIdCollection)
            return DescribeTopicsResult.ofTopicIds(handleDescribeTopicsByIds(((TopicIdCollection) topics).topicIds(), options));
        else if (topics instanceof TopicNameCollection)
            return DescribeTopicsResult.ofTopicNames(handleDescribeTopicsByNamesWithDescribeTopicPartitionsApi(((TopicNameCollection) topics).topicNames(), options));
        else
            throw new IllegalArgumentException("The TopicCollection: " + topics + " provided did not match any supported classes for describeTopics.");
    }

    private Call generateDescribeTopicsCallWithMetadataApi(
        List<String> topicNamesList,
        Map<String, KafkaFutureImpl<TopicDescription>> topicFutures,
        DescribeTopicsOptions options,
        long now
    ) {
        return new Call("describeTopics", calcDeadlineMs(now, options.timeoutMs()),
            new LeastLoadedNodeProvider()) {

            private boolean supportsDisablingTopicCreation = true;

            @Override
            MetadataRequest.Builder createRequest(int timeoutMs) {
                if (supportsDisablingTopicCreation)
                    return new MetadataRequest.Builder(new MetadataRequestData()
                        .setTopics(convertToMetadataRequestTopic(topicNamesList))

View on GitHub (pinned to 996fb4585a)