{"record":{"id":"92d776685d8b90cf","repo":"apache/rocketmq","slug":"subscribe-lite-operation-is-not-supported-for-this","errorCode":null,"errorMessage":"subscribe lite operation is not supported for this group","messagePattern":"subscribe lite operation is not supported for this group","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"broker/src/main/java/org/apache/rocketmq/broker/lite/LiteSubscriptionRegistryImpl.java","lineNumber":90,"sourceCode":"    // Number of active liteTopic references.\n    // [(client1, liteTopic1), (client2, liteTopic1)] counts as two active references.\n    protected final AtomicInteger activeNum = new AtomicInteger(0);\n\n    @Override\n    public void updateClientChannel(String clientId, Channel channel) {\n        clientChannels.put(clientId, channel);\n    }\n\n    @Override\n    public void addPartialSubscription(String clientId, String group, String topic, Set<String> lmqNameSet,\n        OffsetOption offsetOption) {\n        long maxCount = brokerController.getBrokerConfig().getMaxLiteSubscriptionCount();\n        if (getActiveSubscriptionNum() >= maxCount) {\n            // No need to check existence, if reach here, it must be new.\n            throw new LiteQuotaException(\"lite subscription quota exceeded \" + maxCount);\n        }\n        if (LiteMetadataUtil.isWildcardGroup(group, brokerController)) {\n            throw new IllegalStateException(\"subscribe lite operation is not supported for this group\");\n        }\n\n        LiteSubscription thisSub = getOrCreateLiteSubscription(clientId, group, topic);\n        // Utilize existing string object\n        final ClientGroup clientGroup = new ClientGroup(clientId, thisSub.getGroup());\n        for (String lmqName : lmqNameSet) {\n            if (!liteLifecycleManager.isSubscriptionActive(topic, lmqName)) {\n                continue;\n            }\n            thisSub.addLiteTopic(lmqName);\n            // First remove the old subscription\n            if (LiteMetadataUtil.isSubLiteExclusive(group, brokerController)) {\n                excludeClientByLmqName(clientId, group, lmqName);\n                // Boundary case: this client may have a stale tombstone from a previous eviction.\n                // Since it is now actively re-claiming the lmqName, clear its own tombstone so\n                // subsequent popLiteTopic is not blocked by the stale mark.\n                exclusiveEvictionTombstones.remove(clientId, lmqName);\n            }","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/broker/src/main/java/org/apache/rocketmq/broker/lite/LiteSubscriptionRegistryImpl.java#L72-L108","documentation":"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).","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before\nclient.addPartialSubscription(clientId, \"order-*\", topic, lmqSet, offsetOption);\n\n// after\nclient.addPartialSubscription(clientId, \"order-lite-group\", topic, lmqSet, offsetOption);","handlingStrategy":"validation","validationCode":"if (LiteMetadataUtil.isWildcardGroup(group, brokerController)) {\n    throw new IllegalArgumentException(\"use a non-wildcard group for lite subscription\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    registry.addPartialSubscription(clientId, group, topic, lmqSet, option);\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"wildcard\") || e.getMessage().contains(\"not supported\")) {\n        // switch the client to a dedicated lite group and resubscribe\n    }\n}","preventionTips":["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"],"tags":["broker","lite","lmq","consumer-group","wildcard","rocketmq"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}