Kafka Error UNKNOWN_TOPIC_ID
Error code 100 · Retriable Broker
This server does not host this topic ID.
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
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 APIs
This error can be returned by: Fetch · Metadata · OffsetCommit · OffsetFetch · Produce
Debugging Kafka errors? Conduktor Console gives you real-time visibility into your cluster. Explore all errors in the Error Decoder.