apache/rocketmq · error · LiteQuotaException

lite subscription quota exceeded

Error message

lite subscription quota exceeded 

What it means

LiteSubscriptionRegistryImpl.addPartialSubscription() throws LiteQuotaException when the number of active lite (LMQ) subscriptions has reached brokerConfig.maxLiteSubscriptionCount. This is a self-protection cap on lightweight-partial-consumption state, checked before the new subscription is registered; the message suffix carries the configured limit.

Source

Thrown at broker/src/main/java/org/apache/rocketmq/broker/lite/LiteSubscriptionRegistryImpl.java:87

        this.liteLifecycleManager = liteLifecycleManager;
    }

    // Number of active liteTopic references.
    // [(client1, liteTopic1), (client2, liteTopic1)] counts as two active references.
    protected final AtomicInteger activeNum = new AtomicInteger(0);

    @Override
    public void updateClientChannel(String clientId, Channel channel) {
        clientChannels.put(clientId, channel);
    }

    @Override
    public void addPartialSubscription(String clientId, String group, String topic, Set<String> lmqNameSet,
        OffsetOption offsetOption) {
        long maxCount = brokerController.getBrokerConfig().getMaxLiteSubscriptionCount();
        if (getActiveSubscriptionNum() >= maxCount) {
            // No need to check existence, if reach here, it must be new.
            throw new LiteQuotaException("lite subscription quota exceeded " + maxCount);
        }
        if (LiteMetadataUtil.isWildcardGroup(group, brokerController)) {
            throw new IllegalStateException("subscribe lite operation is not supported for this group");
        }

        LiteSubscription thisSub = getOrCreateLiteSubscription(clientId, group, topic);
        // Utilize existing string object
        final ClientGroup clientGroup = new ClientGroup(clientId, thisSub.getGroup());
        for (String lmqName : lmqNameSet) {
            if (!liteLifecycleManager.isSubscriptionActive(topic, lmqName)) {
                continue;
            }
            thisSub.addLiteTopic(lmqName);
            // First remove the old subscription
            if (LiteMetadataUtil.isSubLiteExclusive(group, brokerController)) {
                excludeClientByLmqName(clientId, group, lmqName);
                // Boundary case: this client may have a stale tombstone from a previous eviction.
                // Since it is now actively re-claiming the lmqName, clear its own tombstone so

View on GitHub (pinned to 293f588571)

Solutions

1. Raise maxLiteSubscriptionCount in broker.conf to a value above your expected peak active lite subscription count and restart/reload the broker
2. Audit active lite subscriptions and expire idle ones so leaked subscriptions stop consuming quota
3. Ensure lite clients unsubscribe/clean up on disconnect so counts decay

Example fix

# before (broker.conf)
# maxLiteSubscriptionCount left at default (too small for the workload)

# after (broker.conf)
maxLiteSubscriptionCount=100000

// client/broker-side guard before subscribing lite
if (registry.getActiveSubscriptionNum() >= brokerConfig.getMaxLiteSubscriptionCount()) {
    throw new IllegalStateException("raise maxLiteSubscriptionCount or expire idle subscriptions");
}

try {
    registry.addPartialSubscription(clientId, group, topic, lmqSet, option);
} catch (LiteQuotaException e) {
    // back off, alert operator, or shed load; do not retry-loop immediately
}

When it happens

Trigger: A lite/LMQ client issuing a subscribe (addPartialSubscription) once getActiveSubscriptionNum() >= maxLiteSubscriptionCount; typically a churn of clients subscribing to many distinct LMQ topics pushes the active count over the cap.

Common situations: Lighweight-consumer deployments (lite pull consumers on LMQ topics) scaling past the default quota; subscription leaks — clients reconnecting without releasing old subscriptions keeping the active count high; a deliberately small maxLiteSubscriptionCount in test configs.

Related errors

• subscribe lite operation is not supported for this group
• Consumer group is not allowed to consume.
• subscription is null
• Failed to get max offset in queue
• Failed to get max offset

AI-assisted analysis of apache/rocketmq@293f588571 (2026-08-14). Data as JSON: /api/errors/619301850162b1ab. Report an issue: GitHub.