Kafka Exception UnknownTopicOrPartitionException
org.apache.kafka.common.errors.UnknownTopicOrPartitionException
Retriable
Broker
This topic/partition doesn't exist. This exception is used in contexts where a topic doesn't seem to exist based on possibly stale metadata. This exception is retriable because the topic or partition might subsequently be created.
Common Causes
- Topic does not exist yet and auto.create.topics.enable=false on the broker; producer or consumer references a non-existent topic
- Partition reassignment or broker failure left the metadata cache stale; client is routing to a broker that no longer hosts the partition
- Topic was recently deleted and the client metadata has not refreshed yet
Solutions
- Create the topic explicitly before producing/consuming: kafka-topics.sh --create --topic <name> --partitions N --replication-factor M --bootstrap-server localhost:9092
- Force a metadata refresh on the client side by setting 'metadata.max.age.ms' to a lower value (e.g. 30000) or by restarting the client
- Verify the topic exists and all partitions have leaders: kafka-topics.sh --describe --topic <name> --bootstrap-server localhost:9092; look for 'Leader: none'
Example Stack Trace
org.apache.kafka.common.errors.UnknownTopicOrPartitionException: This server does not host this topic-partition.Diagnostic Commands
# Describe topic partitions, leaders, and ISR
kafka-topics.sh --describe --topic <topic> --bootstrap-server localhost:9092
# List topics and search for the target topic
kafka-topics.sh --list --bootstrap-server localhost:9092 | grep <topic>Related
Protocol error: UNKNOWN_TOPIC_OR_PARTITION (code 3)
Related Broker exceptions: CorruptRecordException · FencedLeaderEpochException · LeaderNotAvailableException · NetworkException · NotEnoughReplicasAfterAppendException · NotEnoughReplicasException · NotLeaderOrFollowerException · TimeoutException
Hitting
UnknownTopicOrPartitionException in production? Conduktor Console gives you real-time visibility into clients, consumer groups, and broker health. Browse every Kafka exception or protocol error code.