What causes "Consumer group is not allowed to consume." in apache/rocketmq?

Update the group's lite subscription metadata to set consumeEnable=true (update lite subscription API/config).

apache/rocketmq · error · IllegalStateException

Consumer group is not allowed to consume.

Error message

Consumer group is not allowed to consume.

What it means

LiteSubscriptionCtlProcessor (lightweight/LMQ subscription control) rejects the operation because LiteMetadataUtil.isConsumeEnable(group, broker) returned false — the group's lite-subscription metadata explicitly forbids consuming. Thrown as IllegalStateException, surfaced to the caller as ILLEGAL_OPERATION.

Source

Thrown at broker/src/main/java/org/apache/rocketmq/broker/processor/LiteSubscriptionCtlProcessor.java:118

                    case COMPLETE_REMOVE:
                        this.liteSubscriptionRegistry.removeCompleteSubscription(clientId);
                        break;
                }
            }
            return RemotingCommand.createResponseCommand(ResponseCode.SUCCESS, null);
        } catch (LiteQuotaException e) {
            return RemotingCommand.createResponseCommand(ResponseCode.LITE_SUBSCRIPTION_QUOTA_EXCEEDED, e.toString());
        } catch (IllegalStateException e) {
            return RemotingCommand.createResponseCommand(ResponseCode.ILLEGAL_OPERATION, e.toString());
        } catch (Exception e) {
            log.error("LiteSubscriptionCtlProcessor error", e);
            return RemotingCommand.createResponseCommand(ResponseCode.SYSTEM_ERROR, e.toString());
        }
    }

    private void checkConsumeEnable(String group) {
        if (!LiteMetadataUtil.isConsumeEnable(group, brokerController)) {
            throw new IllegalStateException("Consumer group is not allowed to consume.");
        }
    }

    private Set<String> toLmqNameSet(LiteSubscriptionDTO liteSubscriptionDTO) {
        if (CollectionUtils.isEmpty(liteSubscriptionDTO.getLiteTopicSet())) {
            return Collections.emptySet();
        }
        return liteSubscriptionDTO.getLiteTopicSet().stream()
            .map(liteTopic -> LiteUtil.toLmqName(liteSubscriptionDTO.getTopic(), liteTopic))
            .collect(Collectors.toSet());
    }

}

View on GitHub (pinned to 293f588571)

Solutions

Update the group's lite subscription metadata to set consumeEnable=true (update lite subscription API/config).
Verify the group exists in lite metadata on this broker and was created via the lite subscription API.
If it was disabled due to quota (LiteQuotaException path), reduce usage or raise the quota first.

Defensive patterns

Strategy: validation

Validate before calling

if (!LiteMetadataUtil.isConsumeEnable(group, brokerController)) {
    // enable in lite subscription metadata or reject the request client-side
}

Try / catch

catch (IllegalStateException e) { if (e.getMessage().contains("not allowed to consume")) { reenableGroupInMetadata(group); } throw e; }

Prevention

Provision lite subscription metadata (consumeEnable=true) before attaching consumers.
Track which groups were administratively disabled so ops knows why consumption fails.

When it happens

Trigger: Any lite-subscription operation path guarded by checkConsumeEnable() when the group's metadata entry consumeEnable=false or is absent for this broker.

Common situations: Group suspended/quota-disabled by an operator; lite subscription metadata not created or not propagated; test environment groups left disabled.

Related errors

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