🚨 Kafka Error Guide: 'UnsupportedVersionException: The broker does not support' — Fix Client/Broker API Mismatch

Overview

UnsupportedVersionException is thrown when a client asks a broker to do something the broker’s API version does not support — a newer client feature against an older broker, or an API the broker has not enabled:

org.apache.kafka.common.errors.UnsupportedVersionException: The broker does not support ALTER_PARTITION_REASSIGNMENTS
org.apache.kafka.common.errors.UnsupportedVersionException: The broker is too old to support the requested feature: idempotent producer
[2026-07-09 14:05:11] ERROR [AdminClient] Call(callName=alterPartitionReassignments) failed: UnsupportedVersionException

It is not retriable — retrying the same request against the same broker will fail identically. The fix is to align versions or stop using the unsupported feature.

Symptoms

• Admin operations (reassignments, incremental config changes, describe features) fail immediately with UnsupportedVersionException.
• A newly upgraded client library starts failing against brokers that previously worked.
• Idempotent/transactional producers or newer consumer-group features fail on older clusters.
• The error names a specific API key (e.g., ALTER_PARTITION_REASSIGNMENTS, OFFSET_DELETE) or feature.
• Failures appear mid-upgrade when inter.broker.protocol.version still points at an old release.

Common Root Causes

• Client newer than broker — a modern client uses an API version the older broker cannot speak.
• Feature requires a newer broker — idempotence, transactions, or newer AdminClient calls need a minimum broker version the cluster is below.
• inter.broker.protocol.version pinned low — mid-upgrade the IBP is still set to the old version, so brokers advertise older API support.
• Mixed-version cluster — some brokers upgraded, others not, so the same call succeeds on one and fails on another.
• Feature not enabled — a KRaft/feature-flag gated capability is not activated on the cluster.

Diagnostic Workflow

Check the broker version the client is talking to:

kafka-broker-api-versions.sh --bootstrap-server localhost:9092 | head -20

List which API keys and versions each broker supports (find the one that is too old):

kafka-broker-api-versions.sh --bootstrap-server localhost:9092 \
  | grep -iE 'AlterPartitionReassignments|Produce|OffsetDelete'

Check the effective inter-broker protocol version across the cluster:

kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type brokers --entity-default --describe | grep -i inter.broker.protocol

Confirm cluster feature levels (KRaft) if a gated feature is involved:

kafka-features.sh --bootstrap-server localhost:9092 describe

Identify the client library version producing the request:

grep -RiE 'kafka-clients|org.apache.kafka' pom.xml build.gradle 2>/dev/null

Example Root Cause Analysis

An automation job that ran partition reassignments via the Java AdminClient started failing with UnsupportedVersionException: The broker does not support ALTER_PARTITION_REASSIGNMENTS after the team upgraded the tool’s kafka-clients dependency. The same cluster had accepted reassignments before via the older ZooKeeper-based script.

kafka-broker-api-versions.sh showed the brokers were still on an older release that predated the AlterPartitionReassignments API, while the newly upgraded client assumed it existed. The AdminClient-based reassignment API simply was not available on those brokers.

Two paths existed: downgrade the client to match the brokers, or upgrade the brokers to a version that supports the API. Because a broker upgrade was already planned, the team temporarily reverted to the legacy kafka-reassign-partitions.sh path (which the old brokers supported) and switched the automation to the AdminClient API only after the brokers were upgraded and inter.broker.protocol.version was bumped. The root cause was a client feature outrunning the broker version.

Prevention Best Practices

• Keep client library versions at or below broker versions, or verify feature support before adopting a newer client.
• During upgrades, upgrade brokers before enabling client features that require the new version, and bump inter.broker.protocol.version only after every broker is on the new binary.
• Avoid long-lived mixed-version clusters; finish rolling upgrades promptly so all brokers advertise the same APIs.
• Use kafka-broker-api-versions.sh in CI to assert the cluster supports every API your clients rely on.
• Read release notes for minimum broker versions when enabling idempotence, transactions, or new AdminClient calls.

Quick Command Reference

# Broker-supported API keys and versions
kafka-broker-api-versions.sh --bootstrap-server localhost:9092

# Inter-broker protocol version
kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-default --describe | grep inter.broker.protocol

# KRaft feature levels
kafka-features.sh --bootstrap-server localhost:9092 describe

# Client library version in the build
grep -RiE 'kafka-clients' pom.xml build.gradle

Conclusion

UnsupportedVersionException is a version-mismatch error, not a transient fault: the client requested a feature or API the broker cannot provide. The fix is alignment — upgrade the brokers, downgrade the client, complete the rolling upgrade, or stop using the unsupported feature. Use kafka-broker-api-versions.sh to see exactly which API is missing, and during upgrades enable new client features only after the brokers and inter.broker.protocol.version support them.