alibaba/spring-cloud-alibaba · error · RuntimeException

group must be configured for DLQ{destination.getName()}

Error message

group must be configured for DLQ{destination.getName()}

What it means

Thrown in RocketMQMessageChannelBinder.createConsumerEndpoint (push consumer) when the consumer is anonymous (no `group`) but the destination name is recognized as a DLQ topic. Spring Cloud Stream requires a concrete group so the DLQ destination can be named deterministically. RocketMQ marks DLQ topics with the `%DLQ%` prefix (detected via NamespaceUtil.isDLQTopic).

Source

Thrown at spring-cloud-alibaba-starters/spring-cloud-starter-stream-rocketmq/src/main/java/com/alibaba/cloud/stream/binder/rocketmq/RocketMQMessageChannelBinder.java:126

	protected MessageHandler createProducerMessageHandler(ProducerDestination destination,
			ExtendedProducerProperties<RocketMQProducerProperties> producerProperties,
			MessageChannel errorChannel) throws Exception {
		throw new UnsupportedOperationException(
				"The abstract binder should not call this method");
	}

	@Override
	protected MessageProducer createConsumerEndpoint(ConsumerDestination destination,
			String group,
			ExtendedConsumerProperties<RocketMQConsumerProperties> extendedConsumerProperties)
			throws Exception {
		boolean anonymous = !StringUtils.hasLength(group);
		/***
		 * 	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(destination.getName())) {
			throw new RuntimeException(
					"group must be configured for DLQ" + destination.getName());
		}
		group = anonymous ? RocketMQUtils.anonymousGroup(destination.getName()) : group;

		RocketMQUtils.mergeRocketMQProperties(binderConfigurationProperties,
				extendedConsumerProperties.getExtension());
		extendedConsumerProperties.getExtension().setGroup(group);

		RocketMQInboundChannelAdapter inboundChannelAdapter = new RocketMQInboundChannelAdapter(
				destination.getName(), extendedConsumerProperties);
		inboundChannelAdapter.setBeanFactory(this.getApplicationContext().getBeanFactory());
		ErrorInfrastructure errorInfrastructure = registerErrorInfrastructure(destination,
				group, extendedConsumerProperties);
		if (extendedConsumerProperties.getMaxAttempts() > 1) {
			inboundChannelAdapter
					.setRetryTemplate(buildRetryTemplate(extendedConsumerProperties));
			inboundChannelAdapter.setRecoveryCallback(errorInfrastructure.getRecoverer());
		}

View on GitHub (pinned to 115d590110)

Solutions

1. Set `spring.cloud.stream.bindings.<input>.group=<stable-group>` so the consumer is not anonymous.
2. If you did not intend DLQ handling, point the binding destination back at the original topic.
3. Verify the destination name does not carry the `%DLQ%` prefix unintentionally.

Example fix

// before - anonymous consumer on a DLQ topic
spring:
  cloud:
    stream:
      bindings:
        dlqInput:
          destination: '%DLQ%myGroup'
          # group missing  -> [121]
# after
spring:
  cloud:
    stream:
      bindings:
        dlqInput:
          destination: '%DLQ%myGroup'
          group: my-dlq-consumer-group

// Reject anonymous DLQ subscriptions before the binder builds the endpoint.
String group = extendedConsumerProperties.getGroup();
boolean anonymous = !StringUtils.hasLength(group);
if (anonymous && org.apache.rocketmq.common.namespace.NamespaceUtil
        .isDLQTopic(destination.getName())) {
    throw new IllegalStateException("Set spring.cloud.stream.bindings.<input>.group for DLQ consumer");
}

When it happens

Trigger: Consuming from a `%DLQ%`-prefixed destination with `spring.cloud.stream.bindings.<input>.group` unset/empty (anonymous consumer).

Common situations: Pointing an input binding at a DLQ topic for retry/replay but forgetting to set `group`; a DLQ name auto-built without a group; migrating a Kafka-style anonymous consumer to a RocketMQ DLQ.

Related errors

• group must be configured for DLQ{topic}
• Binding for channel {destination.getName()} has been disable
• DefaultMQPushConsumer init failed, Caused by {e.getMessage()
• DefaultMQPushConsumer consuming failed, Caused by messageExt
• DefaultMQPushConsumer not initialized

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