alibaba/spring-cloud-alibaba · error · RuntimeException

group must be configured for DLQ{topic}

Error message

group must be configured for DLQ{topic}

What it means

Same DLQ/group rule as [121] but enforced in RocketMQConsumerFactory.initPullConsumer for the pull (pollable) consumer path. Without a group, RocketMQ cannot name the DLQ consumer group, so the factory aborts construction of the DefaultLitePullConsumer.

Source

Thrown at spring-cloud-alibaba-starters/spring-cloud-starter-stream-rocketmq/src/main/java/com/alibaba/cloud/stream/binder/rocketmq/integration/inbound/RocketMQConsumerFactory.java:125

	/**
	 * todo Compatible with versions less than 4.6 ?
	 * @param topic consumer topic.
	 * @param extendedConsumerProperties extendedConsumerProperties
	 * @return DefaultLitePullConsumer
	 */
	public static DefaultLitePullConsumer initPullConsumer(
			String topic,
			ExtendedConsumerProperties<RocketMQConsumerProperties> extendedConsumerProperties) {
		RocketMQConsumerProperties consumerProperties = extendedConsumerProperties
				.getExtension();
		boolean anonymous = !StringUtils.hasLength(consumerProperties.getGroup());
		/***
		 * 	When using DLQ, at least the group property must be provided for proper naming of the DLQ destination
		 *  According to https://docs.spring.io/spring-cloud-stream/docs/3.2.1/reference/html/spring-cloud-stream.html#spring-cloud-stream-reference
		 */
		if (anonymous && NamespaceUtil.isDLQTopic(topic)) {
			throw new RuntimeException(
					"group must be configured for DLQ" + topic);
		}
		if (anonymous) {
			consumerProperties.setGroup(RocketMQUtils.anonymousGroup(topic));
		}
		String consumerGroup = Objects.requireNonNull(consumerProperties.getGroup());

		Assert.notNull(consumerProperties.getNameServer(),
				"Property 'nameServer' is required");
		AllocateMessageQueueStrategy allocateMessageQueueStrategy = RocketMQBeanContainerCache
				.getBean(consumerProperties.getAllocateMessageQueueStrategy(),
						AllocateMessageQueueStrategy.class);

		RPCHook rpcHook = null;
		if (StringUtils.hasLength(consumerProperties.getAccessKey())
				&& StringUtils.hasLength(consumerProperties.getSecretKey())) {
			rpcHook = new AclClientRPCHook(
					new SessionCredentials(consumerProperties.getAccessKey(),

View on GitHub (pinned to 115d590110)

Solutions

1. Set `spring.cloud.stream.rocketmq.bindings.<input>.consumer.group=<id>` (or the generic `bindings.<input>.group`).
2. Re-check the topic name to ensure it is genuinely a DLQ destination; if not, drop the `%DLQ%` prefix.
3. Confirm the pull consumer actually needs DLQ; otherwise consume the source topic.

Example fix

// before - pollable source on DLQ, no group
spring:
  cloud:
    stream:
      bindings:
        dlqPoll:
          destination: '%DLQ%myGroup'
          consumer:
            # pull/pollable, group missing -> [122]
# after
spring:
  cloud:
    stream:
      bindings:
        dlqPoll:
          destination: '%DLQ%myGroup'
          group: my-dlq-pull-group

// Guard before calling initPullConsumer.
boolean anonymous = !StringUtils.hasLength(consumerProperties.getGroup());
if (anonymous && org.apache.rocketmq.common.namespace.NamespaceUtil.isDLQTopic(topic)) {
    throw new IllegalStateException("Pull consumer on DLQ requires a group");
}

When it happens

Trigger: A pull/pollable input binding whose consumerProperties group is empty AND whose topic is a `%DLQ%` topic (NamespaceUtil.isDLQTopic true).

Common situations: Using a pollable source against a DLQ topic without `group`; replay tooling that omits the group.

Related errors

• group must be configured for DLQ{destination.getName()}
• Already acknowledged
• pull consumer already running. {this.toString()}
• The message queue is not in assigned list
• Binding for channel {destination.getName()} has been disable

AI-assisted analysis of alibaba/spring-cloud-alibaba@115d590110 (2026-08-14). Data as JSON: /api/errors/cc87473568aeb632. Report an issue: GitHub.