apache/rocketmq · error · IllegalStateException

subscribe lite operation is not supported for this group

Error message

subscribe lite operation is not supported for this group

What it means

LiteSubscriptionRegistryImpl.addPartialSubscription() rejects lite/LMQ subscriptions whose consumer group matches the configured wildcard-group pattern (LiteMetadataUtil.isWildcardGroup). Wildcard groups use a different metadata/lifecycle mechanism that the lite subscription path does not support, so mixing them is treated as a programming/configuration error (IllegalStateException).

Source

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

    // 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
                // subsequent popLiteTopic is not blocked by the stale mark.
                exclusiveEvictionTombstones.remove(clientId, lmqName);
            }

View on GitHub (pinned to 293f588571)

Solutions

Use a dedicated, non-wildcard consumer group name for lite/LMQ subscriptions
Check the broker-side wildcard group configuration to understand which names are treated as wildcard and rename the client group accordingly

Example fix

// before
client.addPartialSubscription(clientId, "order-*", topic, lmqSet, offsetOption);

// after
client.addPartialSubscription(clientId, "order-lite-group", topic, lmqSet, offsetOption);

Defensive patterns

Strategy: validation

Validate before calling

if (LiteMetadataUtil.isWildcardGroup(group, brokerController)) {
    throw new IllegalArgumentException("use a non-wildcard group for lite subscription");
}

Try / catch

try {
    registry.addPartialSubscription(clientId, group, topic, lmqSet, option);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("wildcard") || e.getMessage().contains("not supported")) {
        // switch the client to a dedicated lite group and resubscribe
    }
}

Prevention

Use a separate group namespace for lite/LMQ consumers that cannot match the wildcard pattern
Document the wildcard group pattern where teams pick group names

When it happens

Trigger: A lite client calling addPartialSubscription with a group name matching the broker's wildcard group expression (e.g. a glob-style group like 'group-*' configured via LiteMetadataUtil-related broker config).

Common situations: Reusing an existing wildcard consumer group name for a new lite-pull deployment; group naming conventions that accidentally collide with the wildcard pattern; misconfigured group in the client's lite subscription request.

Related errors

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