apache/kafka · error · IllegalStateException

Unknown topology node type: {nodeType}

Error message

Unknown topology node type: {nodeType}

What it means

Thrown by DescribeStreamsGroupsHandler.convertTopologyNode when the node.nodeType() byte does not match NODE_TYPE_SOURCE, NODE_TYPE_PROCESSOR, or NODE_TYPE_SINK. The client received a topology node type it does not recognize, indicating either a newer broker adding a new node kind or a corrupt payload.

Source

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

    }

    private StreamsGroupTopologyDescription.Node convertTopologyNode(
            final StreamsGroupDescribeResponseData.TopologyDescriptionNode node,
            final Map<String, Set<String>> predecessors) {
        final Set<String> successors = Set.copyOf(node.successors());
        final Set<String> nodePredecessors = predecessors.getOrDefault(node.name(), Set.of());
        switch (node.nodeType()) {
            case NODE_TYPE_SOURCE:
                return new StreamsGroupTopologyDescription.Source(
                    node.name(), Set.copyOf(node.sourceTopics()), successors, nodePredecessors);
            case NODE_TYPE_PROCESSOR:
                return new StreamsGroupTopologyDescription.Processor(
                    node.name(), Set.copyOf(node.stores()), successors, nodePredecessors);
            case NODE_TYPE_SINK:
                return new StreamsGroupTopologyDescription.Sink(
                    node.name(), Optional.ofNullable(node.sinkTopic()), successors, nodePredecessors);
            default:
                throw new IllegalStateException("Unknown topology node type: " + node.nodeType());
        }
    }

    private StreamsGroupMemberAssignment.TaskIds convertTaskIds(final StreamsGroupDescribeResponseData.TaskIds taskIds) {
        return new StreamsGroupMemberAssignment.TaskIds(
            taskIds.subtopologyId(),
            taskIds.partitions()
        );
    }

    private StreamsGroupMemberAssignment convertAssignment(final StreamsGroupDescribeResponseData.Assignment assignment) {
        return new StreamsGroupMemberAssignment(
            assignment.activeTasks().stream().map(this::convertTaskIds).collect(Collectors.toList()),
            assignment.standbyTasks().stream().map(this::convertTaskIds).collect(Collectors.toList()),
            assignment.warmupTasks().stream().map(this::convertTaskIds).collect(Collectors.toList())
        );
    }

View on GitHub (pinned to 996fb4585a)

Solutions

1. Upgrade the kafka-clients dependency to match the broker version.
2. Restrict the client to API versions supported by both ends.
3. Catch IllegalStateException around describeStreamsGroups and surface a clear 'unsupported version' error.

Example fix

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

// after
try {
    Map<String, StreamsGroupDescription> r =
        admin.describeStreamsGroups(groups).all().get();
} catch (ExecutionException e) {
    if (e.getCause() instanceof IllegalStateException
        && e.getCause().getMessage().contains("Unknown topology node type")) {
        throw new IllegalStateException("Upgrade kafka-clients to match broker", e);
    }
    throw e;
}

// Cannot pre-validate unknown node types; ensure client >= broker version
assert clientVersionIsAtLeast(brokerVersion);

try {
    return admin.describeStreamsGroups(groups).all().get();
} catch (ExecutionException e) {
    if (e.getCause() instanceof IllegalStateException
        && e.getCause().getMessage().contains("Unknown topology node type")) {
        throw new IllegalStateException("kafka-clients out of date; upgrade to match broker", e);
    }
    throw e;
}

When it happens

Trigger: Describing a Streams group whose topology contains a node type byte outside the three known values; common when the broker is newer than the client.

Common situations: Client older than broker (rolling upgrade); experimental Streams features; corrupt response.

Related errors

• Topology description is missing despite status AVAILABLE
• Global store must be composed of a source and a processor no
• 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/c0639ee66b19f488. Report an issue: GitHub.