Simplify Message Failure Handling with RabbitMQ DLQ in Spring Cloud Stream

Application Scenario

Previously we introduced two strategies for handling message failures in Spring Cloud Stream: automatic retry and custom error‑handling logic. When the failure is caused by a bug in the business code, retries are useless and custom logic may be unavailable, so we need a more convenient solution.

Solution: Use RabbitMQ DLQ

By enabling the dead‑letter queue (DLQ) feature of RabbitMQ, failed messages are automatically moved to a dedicated queue for later analysis and re‑processing.

Hands‑On Example

Below is a minimal Spring Boot application that deliberately throws an exception during message consumption.

@EnableBinding(TestApplication.TestTopic.class)
@SpringBootApplication
public class TestApplication {
    public static void main(String[] args) {
        SpringApplication.run(TestApplication.class, args);
    }

    @RestController
    static class TestController {
        @Autowired
        private TestTopic testTopic;

        @GetMapping("/sendMessage")
        public String messageWithMQ(@RequestParam String message) {
            testTopic.output().send(MessageBuilder.withPayload(message).build());
            return "ok";
        }
    }

    @Slf4j
    @Component
    static class TestListener {
        @StreamListener(TestTopic.INPUT)
        public void receive(String payload) {
            log.info("Received payload : " + payload);
            throw new RuntimeException("Message consumer failed!");
        }
    }

    interface TestTopic {
        String OUTPUT = "example-topic-output";
        String INPUT = "example-topic-input";

        @Output(OUTPUT)
        MessageChannel output();

        @Input(INPUT)
        SubscribableChannel input();
    }
}

The application produces a message via /sendMessage?message=hello and the consumer deliberately fails, triggering the DLQ handling.

Configuration

Add the following properties (e.g., in application.yml) to bind the logical channels to physical RabbitMQ destinations and enable the DLQ:

spring:
  cloud:
    stream:
      bindings:
        example-topic-input:
          destination: test-topic
          group: stream-exception-handler
          consumer:
            max-attempts: 1
        example-topic-output:
          destination: test-topic
      rabbit:
        bindings:
          example-topic-input:
            consumer:
              auto-bind-dlq: true

After starting the application, visit http://localhost:8080/sendMessage?message=hello. The consumer logs the failure and the message is automatically routed to the DLQ queue test-topic.stream-exception-handler.dlq.

In the RabbitMQ management console you can see the DLQ:

To reprocess messages, use the "Move messages" feature to transfer them back to the original queue.

Advanced Scenarios

For time‑sensitive messages, set a TTL for the DLQ so that stale messages expire automatically:

spring.cloud.stream.rabbit.bindings.example-topic-input.consumer.dlq-ttl=10000

To retain the original error information when moving messages to the DLQ, enable republishing:

spring.cloud.stream.rabbit.bindings.example-topic-input.consumer.republish-to-dlq=true

This adds exception details to the message headers, allowing downstream consumers to differentiate failure reasons.

These configurations cover the most common DLQ use‑cases. For additional options, refer to the official Spring Cloud Stream RabbitMQ binder documentation.