Kafka Exception ThrottlingQuotaExceededException
org.apache.kafka.common.errors.ThrottlingQuotaExceededException
Retriable
Admin
Exception thrown if an operation on a resource exceeds the throttling quota.
Common Causes
- Client (producer, consumer, or admin) exceeded a quota key such as producer_byte_rate, consumer_byte_rate, or request_percentage configured for its user, client-id, or user/client-id pair
- A bulk admin operation (topic creation, config changes, metadata fetches) hit the controller mutation quota (controller_mutation_rate)
- Sudden traffic spike from a producer or consumer that was not previously quota-limited, e.g. after a deployment or data backfill
Solutions
- Describe the exact quota entity first (user, client-id, or both), then raise only the exceeded key: producer_byte_rate, consumer_byte_rate, request_percentage, or controller_mutation_rate
- Respect throttle_time_ms from the response and back off before retrying; repeated immediate retries only extend the throttle window
- If this started after a deployment or replay, reduce concurrency or batch rate on that client instead of only raising quotas
Example Stack Trace
org.apache.kafka.common.errors.ThrottlingQuotaExceededException: The throttling quota has been exceeded.Diagnostic Commands
# Check client quota configuration
kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type clients --entity-name <client-id>
# Check user-side quota configuration
kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type users --entity-name <user>Related
Protocol error: THROTTLING_QUOTA_EXCEEDED (code 89)
Related Admin exceptions: InvalidConfigurationException · InvalidPartitionsException · InvalidReplicationFactorException · InvalidTopicException · PolicyViolationException · TopicExistsException · UnsupportedVersionException
Hitting
ThrottlingQuotaExceededException in production? Conduktor Console gives you real-time visibility into clients, consumer groups, and broker health. Browse every Kafka exception or protocol error code.