apache/pulsar · error · ConsumerAssignException

No more range can assigned to new consumer, assigned consume

Error message

No more range can assigned to new consumer, assigned consumers ${rangeMap.size()}

What it means

HashRangeAutoSplitStickyKeyConsumerSelector splits an existing hash range when a new consumer joins key_shared subscription. If the chosen range is too small to split (range - lowerKey <= 1), it throws ConsumerAssignException because no further range can be assigned.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/HashRangeAutoSplitStickyKeyConsumerSelector.java:188

            Integer lowerKey = rangeMap.lowerKey(entry.getKey());
            if (lowerKey == null) {
                lowerKey = 0;
            }
            if (entry.getKey() - lowerKey > slots) {
                slots = entry.getKey() - lowerKey;
                busiestRange = entry.getKey();
            }
        }
        return busiestRange;
    }

    private void splitRange(int range, Consumer targetConsumer) throws ConsumerAssignException {
        Integer lowerKey = rangeMap.lowerKey(range);
        if (lowerKey == null) {
            lowerKey = 0;
        }
        if (range - lowerKey <= 1) {
            throw new ConsumerAssignException("No more range can assigned to new consumer, assigned consumers "
                    + rangeMap.size());
        }
        int splitRange = range - ((range - lowerKey) >> 1);
        rangeMap.put(splitRange, targetConsumer);
        consumerRange.put(targetConsumer, splitRange);
    }

    private boolean is2Power(int num) {
        if (num < 2) {
            return false;
        }
        return (num & num - 1) == 0;
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Reduce the number of consumers attached to the single key_shared subscription
2. Recreate the subscription (disconnect all consumers) to reset hash ranges to a fresh state
3. Switch key_shared mode to StickyKeyConsumerSelector hash ranges config or use a different subscription type (Shared) for very high consumer counts
4. Catch ConsumerAssignException on subscribe and retry later after consumers disconnect

// keep consumer count of the key_shared subscription well below the range space
long consumers = subscription.getConsumers().size();
boolean canJoin = consumers < 65536;

try {
    consumer = pulsarClient.newConsumer().subscriptionType(SubscriptionType.Key_Shared)...subscribe();
} catch (PulsarClientException e) {
    if (e.getCause() instanceof ConsumerAssignException) { /* backoff and retry */ }
}

When it happens

Trigger: Adding a consumer to a key_shared subscription with auto-split key sharing when the number of consumers exceeds the number of available hash-range units (range space exhausted, 65536 ranges).

Common situations: Subscribing with an extremely large number of consumers on one key_shared subscription; pathological range fragmentation after many consumer add/remove cycles; simulated/tests using tiny hash ranges.

Related errors

• Range conflict with consumer ${conflictingConsumer}
• ${key} already exists in the dynamicConfigurationMap
• Topic factory failed to create topic
• Error creating client for HealthChecker
• configuredService should not be an instance of SystemTopicBa

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/611eb345094f1b4b. Report an issue: GitHub.