apache/kafka · error · IllegalStateException

Offsets from multiple consumer groups were requested. Use…

Error message

Offsets from multiple consumer groups were requested. Use partitionsToOffsetAndMetadata(groupId) instead to get future for a specific group.

What it means

An IllegalStateException thrown by ListConsumerGroupOffsetsResult.partitionsToOffsetAndMetadata() (the no-arg overload) when more than one consumer group was requested. The no-arg accessor assumes exactly one group; with multiple groups you must ask for each by id.

Solutions

When listing multiple groups, call partitionsToOffsetAndMetadata(groupId) for each group, or use all() to get every group's offsets at once.
If you genuinely want a single group, use Admin.listConsumerGroupOffsets(String singleGroupId) instead of the Map overload.

Example fix

// before
Map<String, ListTopicsOptions> groups = Map.of("g1", opts, "g2", opts);
ListConsumerGroupOffsetsResult r = admin.listConsumerGroupOffsets(groups);
r.partitionsToOffsetAndMetadata(); // throws

// after
for (String g : groups.keySet()) {
    r.partitionsToOffsetAndMetadata(g);
}

Defensive patterns

Strategy: validation

Validate before calling

if (groupIds.size() == 1) {
    result.partitionsToOffsetAndMetadata();
} else {
    for (String g : groupIds) result.partitionsToOffsetAndMetadata(g);
}

Type guard

static boolean isSingleGroup(ListConsumerGroupOffsetsResult r) {
    // heuristic: only call no-arg accessor when you know you requested one group
    return requestedGroupIds.size() == 1;
}

Prevention

Use the no-arg accessor only when you requested exactly one group.
For multi-group requests, iterate known ids or use all().

When it happens

Trigger: Calling Admin.listConsumerGroupOffsets(Map<String, ListTopicsOptions>) with a map of size > 1, then calling result.partitionsToOffsetAndMetadata() (no arg). Also when the single-group overload was expected but the request was built with a multi-group API.

Common situations: Refactoring from listing one group to listing several but keeping the no-arg accessor; helper code that assumes single-group usage but is reused in a batch context.

Related errors

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

Appendix: source

Thrown at clients/src/main/java/org/apache/kafka/clients/admin/ListConsumerGroupOffsetsResult.java:53

 * <p>
 */
@InterfaceAudience.Public
public class ListConsumerGroupOffsetsResult {

    final Map<String, KafkaFuture<Map<TopicPartition, OffsetAndMetadata>>> futures;

    ListConsumerGroupOffsetsResult(final Map<CoordinatorKey, KafkaFuture<Map<TopicPartition, OffsetAndMetadata>>> futures) {
        this.futures = futures.entrySet().stream()
                .collect(Collectors.toMap(e -> e.getKey().idValue, Entry::getValue));
    }

    /**
     * Return a future which yields a map of topic partitions to OffsetAndMetadata objects.
     * If the group does not have a committed offset for this partition, the corresponding value in the returned map will be null.
     */
    public KafkaFuture<Map<TopicPartition, OffsetAndMetadata>> partitionsToOffsetAndMetadata() {
        if (futures.size() != 1) {
            throw new IllegalStateException("Offsets from multiple consumer groups were requested. " +
                    "Use partitionsToOffsetAndMetadata(groupId) instead to get future for a specific group.");
        }
        return futures.values().iterator().next();
    }

    /**
     * Return a future which yields a map of topic partitions to OffsetAndMetadata objects for
     * the specified group. If the group doesn't have a committed offset for a specific
     * partition, the corresponding value in the returned map will be null.
     */
    public KafkaFuture<Map<TopicPartition, OffsetAndMetadata>> partitionsToOffsetAndMetadata(String groupId) {
        if (!futures.containsKey(groupId))
            throw new IllegalArgumentException("Offsets for consumer group '" + groupId + "' were not requested.");
        return futures.get(groupId);
    }

    /**
     * Return a future which yields all {@code Map<String, Map<TopicPartition, OffsetAndMetadata>} objects,

View on GitHub (pinned to 996fb4585a)