apache/kafka · error · IllegalStateException

Topology description is missing despite status AVAILABLE

Error message

Topology description is missing despite status AVAILABLE

What it means

Thrown by DescribeStreamsGroupsHandler.convertTopologyDescription when the broker reported StreamsGroupTopologyDescriptionStatus.AVAILABLE but the topologyDescription field of the response is null. This is an IllegalStateException because it represents a contract violation by the broker: AVAILABLE implies a non-null payload. Clients cannot recover the missing description.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/admin/internals/DescribeStreamsGroupsHandler.java:236

                topicInfo.partitions(),
                topicInfo.replicationFactor(),
                topicInfo.topicConfigs().stream().collect(Collectors.toMap(
                    StreamsGroupDescribeResponseData.KeyValue::key,
                    StreamsGroupDescribeResponseData.KeyValue::value
                ))
            )
        ));
    }

    private Optional<StreamsGroupTopologyDescription> convertTopologyDescription(
            final StreamsGroupTopologyDescriptionStatus status,
            final StreamsGroupDescribeResponseData.TopologyDescription topologyDescription) {

        if (status != StreamsGroupTopologyDescriptionStatus.AVAILABLE) {
            return Optional.empty();
        }
        if (topologyDescription == null) {
            throw new IllegalStateException("Topology description is missing despite status AVAILABLE");
        }
        final List<StreamsGroupTopologyDescription.Subtopology> subtopologies = topologyDescription.subtopologies().stream()
            .map(this::convertTopologySubtopology)
            .collect(Collectors.toList());
        final List<StreamsGroupTopologyDescription.GlobalStore> globalStores = topologyDescription.globalStores().stream()
            .map(this::convertGlobalStore)
            .collect(Collectors.toList());
        return Optional.of(new StreamsGroupTopologyDescription(subtopologies, globalStores));
    }

    private StreamsGroupTopologyDescription.Subtopology convertTopologySubtopology(
            final StreamsGroupDescribeResponseData.TopologyDescriptionSubtopology subtopology) {
        final Map<String, Set<String>> predecessors = reconstructPredecessors(subtopology.nodes());
        final List<StreamsGroupTopologyDescription.Node> nodes = subtopology.nodes().stream()
            .map(node -> convertTopologyNode(node, predecessors))
            .collect(Collectors.toList());
        return new StreamsGroupTopologyDescription.Subtopology(subtopology.subtopologyId(), nodes);
    }

View on GitHub (pinned to 996fb4585a)

Solutions

1. Upgrade or roll back the broker so client and server agree on the response schema.
2. File a broker-side bug; this is not a client configuration issue.
3. Catch IllegalStateException from describeStreamsGroups and degrade gracefully (e.g. report topology unavailable).

Example fix

// before
Map<String, StreamsGroupDescription> r =
    admin.describeStreamsGroups(List.of(g)).all().get();

// after
try {
    Map<String, StreamsGroupDescription> r =
        admin.describeStreamsGroups(List.of(g)).all().get();
} catch (ExecutionException e) {
    if (e.getCause() instanceof IllegalStateException) {
        log.warn("Broker returned inconsistent streams topology for {}; reporting unavailable", g, e);
    } else throw e;
}

// Cannot pre-validate broker response; mitigate by ensuring version alignment
assert clientVersionIsAtLeast(brokerVersion);

try {
    return admin.describeStreamsGroups(groups).all().get();
} catch (ExecutionException e) {
    if (e.getCause() instanceof IllegalStateException) {
        log.warn("Inconsistent streams describe response; possible broker bug or version skew", e);
        return Collections.emptyMap();
    }
    throw e;
}

When it happens

Trigger: Receiving a StreamsGroupDescribeResponse where status == AVAILABLE but topologyDescription == null. Emitted from admin.describeStreamsGroups when the response is parsed.

Common situations: Broker bug or version skew during a rolling upgrade; a corrupt or partially-serialized response; an experimental/unstable broker build that omits the payload.

Related errors

• Global store must be composed of a source and a processor no
• Unknown topology node type: {nodeType}
• Unknown topology description status id: {id}
• Unknown acknowledge type id: {id}
• Unknown rebalance protocol id: {id}

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