apache/kafka · error · IllegalArgumentException

Unknown topology description status id: {id}

Error message

Unknown topology description status id: {id}

What it means

Thrown by StreamsGroupTopologyDescriptionStatus.forId(byte) when deserializing a Streams group topology status from the broker and the wire id does not match any defined enum value. The enum maps broker-reported topology description states to client-side constants; an unknown id means the client cannot interpret a status the broker sent. This almost always indicates a broker/client version skew where a newer broker introduced a status id the older client does not recognize.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/admin/StreamsGroupTopologyDescriptionStatus.java:82

     */
    public byte id() {
        return id;
    }

    /**
     * Returns the status corresponding to the given wire identifier.
     *
     * @param id the wire identifier.
     * @return the matching status.
     * @throws IllegalArgumentException if the identifier is unknown.
     */
    public static StreamsGroupTopologyDescriptionStatus forId(final byte id) {
        for (final StreamsGroupTopologyDescriptionStatus status : values()) {
            if (status.id == id) {
                return status;
            }
        }
        throw new IllegalArgumentException("Unknown topology description status id: " + id);
    }
}

View on GitHub (pinned to c31c9215e1)

Solutions

1. Upgrade the Kafka client library to match (or exceed) the broker version that introduced the new status id.
2. Pin the broker feature to a version compatible with the deployed client until clients are upgraded.
3. Check the broker logs/release notes for the StreamsGroupTopologyDescriptionStatus enum to identify the new id and its meaning.

Example fix

// before: client older than broker
<dependency>
  <groupId>org.apache.kafka</groupId>
  <artifactId>kafka-clients</artifactId>
  <version>3.7.0</version>
</dependency>

// after: align client with broker
<dependency>
  <groupId>org.apache.kafka</groupId>
  <artifactId>kafka-clients</artifactId>
  <version>3.9.0</version> <!-- match broker version -->
</dependency>

// StreamsGroupTopologyDescriptionStatus.forId is driven by broker wire data the user cannot validate ahead of time.
StreamsGroupTopologyDescriptionStatus status;
try {
    status = StreamsGroupTopologyDescriptionStatus.forId(rawId);
} catch (IllegalArgumentException e) {
    log.warn("Broker returned unknown topology description status id {} - client/broker version skew likely", rawId);
    status = StreamsGroupTopologyDescriptionStatus.ERROR; // safe fallback
}

When it happens

Trigger: Deserialization of a DescribeStreamsGroupResponse (AdminClient.describeStreamsGroups) where the broker returns a topology description status byte not present in the client's compiled enum. Internal: the forId loop at line 77 falls through without a match.

Common situations: Rolling upgrade of a Kafka cluster to a version that adds new StreamsGroupTopologyDescriptionStatus values while client applications still run an older client library; mixed-version clusters during upgrade windows; brokers with experimental/new Streams group features enabled.

Related errors

• Unknown acknowledge type id: {id}
• Unknown rebalance protocol id: {id}
• Member {member} was not included in the original request
• Expected 0 <= minVersion <= maxVersion but received minVersi
• Buffer underflow while parsing response for request with hea

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