Kafka Error REBOOTSTRAP_REQUIRED
Error code 129 · Non-retriable KRaft
Client metadata is stale. The client should rebootstrap to obtain new metadata.
Common Causes
- The client's cached cluster metadata is so stale (e.g., all known brokers have been replaced, cluster has been migrated, or broker IDs have changed) that incremental metadata refresh is insufficient and a full rebootstrap is required.
- KRaft cluster underwent a major topology change (e.g., full controller quorum replacement, cluster UUID change, or migration from ZooKeeper to KRaft) that invalidated all cached broker endpoints.
- Client has been running with stale metadata for longer than the cluster's metadata validity window, and the broker explicitly signals that a fresh discovery from bootstrap servers is needed.
Solutions
- The client must reinitialize from the configured `bootstrap.servers` list — close the current `KafkaProducer`/`KafkaConsumer` and recreate it. This forces a fresh metadata fetch from scratch.
- Ensure `bootstrap.servers` is configured with multiple brokers (at least 3) and uses DNS-resolvable hostnames rather than IPs, so that rebootstrap succeeds even if some brokers have changed IP addresses.
- In long-running clients, implement reconnection logic that handles `REBOOTSTRAP_REQUIRED` by triggering a full client recreation rather than just a metadata refresh. Add alerting for this error as it signals significant cluster topology change.
Diagnostic Commands
# Check broker supported API versions
kafka-broker-api-versions.sh --bootstrap-server localhost:9092 --command-config admin.properties
# Look for rebootstrap events in logs
grep 'REBOOTSTRAP_REQUIRED\|rebootstrap\|stale metadata\|bootstrap' /var/log/kafka/server.log | tail -50
Debugging Kafka errors? Conduktor Console gives you real-time visibility into your cluster. Explore all errors in the Error Decoder.