apache/kafka · error · IllegalArgumentException

Unknown topology description status id

Error message

Unknown topology description status id: {id}

What it means

Thrown by StreamsGroupTopologyDescriptionStatus.forId(byte) when no enum constant matches the wire id received in a StreamsGroupDescribe response. This indicates the broker sent a topology description status value unknown to this client version. The enum is part of the consumer protocol surface and only grows when new statuses are added in newer broker versions.

Solutions

1. Upgrade the Kafka client library to match (or exceed) the broker version.
2. Pin the broker's inter-broker and client-facing API versions to a range the client supports.
3. Catch IllegalArgumentException during describeStreamsGroups and report an unsupported-version diagnostic.

Example fix

// before
StreamsGroupDescription desc = admin.describeStreamsGroups(List.of(group))
    .all().get().get(group);

// after
try {
    StreamsGroupDescription desc = admin.describeStreamsGroups(List.of(group))
        .all().get().get(group);
} catch (ExecutionException e) {
    if (e.getCause() instanceof IllegalArgumentException
        && e.getCause().getMessage().contains("Unknown topology description status id")) {
        throw new IllegalStateException("Client version too old for broker; upgrade kafka-clients", e);
    }
    throw e;
}

// Cannot pre-validate wire bytes; ensure client version >= broker version
assert clientVersionIsAtLeast(brokerVersion) : "upgrade kafka-clients";

try {
    return admin.describeStreamsGroups(groups).all().get();
} catch (ExecutionException e) {
    if (e.getCause() instanceof IllegalArgumentException
        && e.getCause().getMessage().contains("Unknown topology description status id")) {
        throw new IllegalStateException("Upgrade kafka-clients to match broker", e);
    }
    throw e;
}

When it happens

Trigger: Calling StreamsGroupTopologyDescriptionStatus.forId with a byte value not among the declared enum ids. Encountered during deserialization of a StreamsGroupDescribeResponse from a newer broker that introduced a new status value.

Common situations: Client older than broker; rolling upgrade where the client hits a controller/broker that already speaks a newer protocol; corrupt or unexpected response from a misbehaving broker.

Related errors

• Global store must be composed of a source and a processor…
• Topology description is missing despite status AVAILABLE
• Unknown topology node type
• Unknown acknowledge type id
• Unknown rebalance protocol id

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

Appendix: 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 996fb4585a)