Kafka Exception UnknownTopicIdException
org.apache.kafka.common.errors.UnknownTopicIdException
Retriable
Broker
UnknownTopicIdException is a Kafka exception (org.apache.kafka.common.errors.UnknownTopicIdException).
Common Causes
- Consumer or fetch request referenced a topic UUID that was valid before the topic was deleted and recreated — the UUID changed, but the client cached the old one
- Metadata cache on the broker is stale and does not yet have the topic ID registered, typically during topic creation propagation in a large cluster
- Client connected to a broker that has not yet received the topic assignment from the KRaft controller
Solutions
- This error is retriable — the client should refresh metadata and retry; ensure client metadata refresh logic is working (metadata.max.age.ms)
- If the error persists after metadata refresh, verify the topic exists and has propagated to all brokers: kafka-topics.sh --describe on multiple brokers
- After topic deletion and recreation, force clients to clear their cached topic ID by triggering a full metadata refresh or restarting the consumer
Example Stack Trace
org.apache.kafka.common.errors.UnknownTopicIdException: This server does not host this topic ID.Diagnostic Commands
# Describe topic partitions, leaders, and ISR
kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic <topic-name>
# Check KRaft metadata quorum status
kafka-metadata-quorum.sh --bootstrap-server localhost:9092 describe --status | grep -E 'HighWatermark|Applied'Related
Protocol error: UNKNOWN_TOPIC_ID (code 100)
Related Broker exceptions: CorruptRecordException · FencedLeaderEpochException · LeaderNotAvailableException · NetworkException · NotEnoughReplicasAfterAppendException · NotEnoughReplicasException · NotLeaderOrFollowerException · TimeoutException
Hitting
UnknownTopicIdException in production? Conduktor Console gives you real-time visibility into clients, consumer groups, and broker health. Browse every Kafka exception or protocol error code.