Kafka Exception UnsupportedVersionException
Indicates that a request API or version needed by the client is not supported by the broker. This is typically a fatal error as Kafka clients will downgrade request versions as needed except in cases where a needed feature is not available in old versions. Fatal errors can generally only be handled by closing the client instance, although in some cases it may be possible to continue without relying on the underlying feature. For example, when the producer is used with idempotence enabled, this error is fatal since the producer does not support reverting to weaker semantics. On the other hand, if this error is raised from offsetsForTimes(Map), it would be possible to revert to alternative logic to set the consumer's position.
Common Causes
- Client library version is newer than the broker and uses an API version the broker does not support (common during cluster upgrades)
- Client has inter.broker.protocol.version or log.message.format.version pinned to an old value, causing brokers to advertise limited API versions
- Client connected to a non-Kafka endpoint (wrong port, load balancer stripping protocol frames) that speaks an incompatible protocol
Solutions
- During rolling upgrades, keep clients on the current version until all brokers are upgraded, then upgrade clients; follow the Kafka upgrade guide ordering
- After a full broker upgrade, remove any old inter.broker.protocol.version or log.message.format.version pins that are still limiting what the brokers advertise
- Use a client version compatible with the broker release and fix any wrong-port or non-Kafka endpoint issues in bootstrap.servers rather than trying to override API negotiation
Example Stack Trace
org.apache.kafka.common.errors.UnsupportedVersionException: The version of API is not supported.Diagnostic Commands
# Verify broker connectivity and API versions
kafka-broker-api-versions.sh --bootstrap-server localhost:9092 2>&1 | grep -E 'Produce|Fetch|Metadata' | head -10
# Check broker protocol version settings
kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-default --describe | grep -E 'inter.broker.protocol|log.message.format'Related
Protocol error: UNSUPPORTED_VERSION (code 35)
Related Admin exceptions: InvalidConfigurationException · InvalidPartitionsException · InvalidReplicationFactorException · InvalidTopicException · PolicyViolationException · ThrottlingQuotaExceededException · TopicExistsException
UnsupportedVersionException in production? Conduktor Console gives you real-time visibility into clients, consumer groups, and broker health. Browse every Kafka exception or protocol error code.