apache/kafka · error · IllegalArgumentException

The TopicCollection: {topics} provided did not match any sup

Error message

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

What it means

Thrown by KafkaAdminClient.describeTopics(TopicCollection, DescribeTopicsOptions) when the passed TopicCollection is neither a TopicIdCollection nor a TopicNameCollection. Like deleteTopics, describeTopics dispatches on these two concrete subtypes (handleDescribeTopicsByIds vs handleDescribeTopicsByNamesWithDescribeTopicPartitionsApi); any other TopicCollection implementation has no defined RPC mapping and is rejected with IllegalArgumentException.

Source

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

                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 c31c9215e1)

Solutions

Build the collection with TopicCollection.ofTopicNames(names) or TopicCollection.ofTopicIds(ids), or call the convenience admin.describeTopics(Collection<String>) overload.
If you must subclass TopicCollection, extend TopicNameCollection or TopicIdCollection so the dispatch instanceof matches.
Do not pass custom TopicCollection implementations to describeTopics(TopicCollection, DescribeTopicsOptions).

Example fix

// before - custom TopicCollection subclass
admin.describeTopics(myCustomTopicCollection, new DescribeTopicsOptions()); // throws

// after
TopicCollection topics = TopicCollection.ofTopicIds(List.of(topicId1, topicId2));
admin.describeTopics(topics, new DescribeTopicsOptions());

Defensive patterns

Strategy: type-guard

Type guard

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

Try / catch

if (!(topics instanceof TopicIdCollection || topics instanceof TopicNameCollection)) {
    throw new IllegalArgumentException("Use TopicCollection.ofTopicNames(...) or TopicCollection.ofTopicIds(...)");
}
admin.describeTopics(topics, options);

Prevention

Only the two shipped TopicCollection subtypes are accepted by describeTopics; build them with TopicCollection.ofTopicNames(...)/ofTopicIds(...).
Keep a single factory method in your codebase that returns TopicCollection so an unsupported subtype never reaches the API.
Mirror the same guard used for deleteTopics — both APIs enforce the identical type check.

When it happens

Trigger: Calling admin.describeTopics(topicCollection, opts) with a TopicCollection that is not a TopicIdCollection or TopicNameCollection — e.g. a custom subclass, a mock, or a placeholder constructed outside the supported factories.

Common situations: Custom wrapper abstraction over TopicCollection; version/fork mismatch; reflection-built collection object; test code passing a stubbed TopicCollection.

Related errors

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