🚨 Kafka Error Guide: 'ThrottlingQuotaExceededException: The throttling quota has been exceeded' — Manage Client Quotas and Backoff

Overview

ThrottlingQuotaExceededException is returned when a request exceeds a configured quota and the broker throttles it — most visibly for controller-mutation quotas on topic create/delete/partition operations:

org.apache.kafka.common.errors.ThrottlingQuotaExceededException: The throttling quota has been exceeded.
[2026-07-09 13:40:18] WARN [AdminClient] createTopics request throttled for 21374 ms; controller mutation quota exceeded

Unlike silent byte-rate throttling (which just delays responses), this exception surfaces when a mutating admin request is rejected for exceeding its rate. It is retriable after the indicated backoff, but a flood of it means the client is issuing operations faster than the quota permits.

Symptoms

• Bulk topic creation/deletion or partition changes fail or stall with ThrottlingQuotaExceededException.
• AdminClient logs show large throttled for N ms values before requests complete.
• Automation that provisions many topics at once slows dramatically or errors out.
• Produce/fetch clients see rising throttle-time JMX metrics without hard errors (byte-rate quotas), while admin clients get the exception.
• The errors concentrate on one user/client-id that recently increased its request rate.

Common Root Causes

• Controller-mutation quota hit — controller_mutation_rate limits how fast a principal can create/delete topics or add partitions; bulk provisioning exceeds it.
• Producer/consumer byte-rate quota — producer_byte_rate/consumer_byte_rate set for the entity is lower than the client’s traffic.
• Request-percentage quota — request_percentage caps CPU time; a chatty client with tiny frequent requests hits it.
• Default quota too tight — an aggressive default quota applies to an unclassified client-id.
• No client-side backoff — automation retries immediately instead of honoring the throttle window, amplifying the problem.

Diagnostic Workflow

List the quotas configured for the affected user/client-id:

kafka-configs.sh --bootstrap-server localhost:9092 \
  --describe --entity-type users --entity-type clients --entity-default

Describe a specific client’s quotas:

kafka-configs.sh --bootstrap-server localhost:9092 \
  --describe --entity-type clients --entity-name provisioner

Check controller-mutation quota specifically (topic/partition operations):

kafka-configs.sh --bootstrap-server localhost:9092 \
  --describe --entity-type users --entity-name provisioner | grep -i controller_mutation_rate

Observe throttle-time on the broker via JMX-exported metrics if scraped:

grep -iE 'throttle-time|controller_mutation' /var/log/kafka/server.log | tail

Example Root Cause Analysis

A platform team ran a migration script that created several thousand topics in a tight loop. After the first few hundred, createTopics calls began returning ThrottlingQuotaExceededException with throttle times climbing into tens of seconds, and the migration ground to a crawl.

kafka-configs.sh --describe showed a controller_mutation_rate quota on the provisioner principal — deliberately set by the cluster admins so no single client could overwhelm the controller with topic churn. The migration’s fire-hose loop blew straight through it. The quota was working as designed; the script was the problem.

The fix was to make the script quota-aware: honor the throttle time the broker returned (the AdminClient exposes it), pace topic creation to stay just under controller_mutation_rate, and batch operations. With backoff in place, the migration completed steadily without further exceptions. The team also temporarily raised the provisioner’s mutation quota during the migration window, then restored it — a controlled change rather than removing the guardrail entirely.

Prevention Best Practices

• Make bulk-provisioning tooling quota-aware: honor the broker-returned throttle time and pace requests below the limit.
• Set controller_mutation_rate deliberately so runaway topic churn cannot destabilize the controller, and raise it consciously for planned migrations.
• Size producer_byte_rate/consumer_byte_rate from measured peaks plus headroom so legitimate traffic is not throttled.
• Roll out quota changes in monitor-then-enforce mode and watch throttle-time metrics before tightening.
• Communicate quotas to tenants so throttling is understood as policy, not an outage.
• Add exponential backoff to admin automation so it never hammers the controller after a throttle response.

Quick Command Reference

# Default user/client quotas
kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type users --entity-type clients --entity-default

# A specific client's quotas
kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type clients --entity-name provisioner

# Set a controller-mutation quota
kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config 'controller_mutation_rate=50' --entity-type users --entity-name provisioner

# Set a producer byte-rate quota
kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config 'producer_byte_rate=10485760' --entity-type clients --entity-name app1

Conclusion

ThrottlingQuotaExceededException is Kafka enforcing a quota — usually the controller-mutation rate during bulk topic operations, or a byte-rate/request-percentage limit on a busy client. It is retriable and, more often than not, the quota is doing exactly what it should. Make clients quota-aware so they honor the throttle window, pace bulk operations, and size quotas from real traffic. Raise limits deliberately for planned work rather than removing the guardrails that protect the cluster.