When a message fails to be consumed after the maximum number of retries, it becomes a dead-letter message. This is the only condition that produces a dead-letter message. By default, ApsaraMQ for RocketMQ discards dead-letter messages. To retain them for recovery or troubleshooting, enable the dead-letter message saving feature to route them to a dedicated dead-letter topic.
How it works
Dead-letter messages are the terminal state in the consumption retry lifecycle:
A consumer receives a message and fails to process it.
The broker retries delivery up to the configured maximum retry count.
If the message still fails after all retries, it becomes a dead-letter message.
To retain dead-letter messages instead of discarding them, enable the dead-letter message saving feature in the console. Dead-letter messages are then saved to a designated dead-letter topic.
What happens when a message is saved to a dead-letter topic
A new message ID is generated.
Custom attributes and the message body remain unchanged.
The retention period starts from the time the message is saved to the dead-letter topic, not from the original delivery time. For example, if a message is delivered to the broker at 13:00:00 and becomes a dead-letter message at 15:00:00, its retention period starts at 15:00:00.
Enable dead-letter message saving
To enable dead-letter message saving in the ApsaraMQ for RocketMQ console:
On the Instances page, click the instance name.
In the left-side navigation pane, click Groups. On the Groups page, click Create Group.
Process dead-letter messages
Subscribe a dedicated consumer group to the dead-letter topic to consume and troubleshoot failed messages separately from normal business traffic.
Track the original topic
To identify which topic a dead-letter message originated from, use one of these approaches:
Naming convention: Map the dead-letter topic name to the original topic name. For example, if the original topic is
testTopic, name the dead-letter topicDLQ-testTopic.Custom attribute: Include the original topic in a message property:
messageBuilder.addProperty("originalTopic", "testTopic")
Avoid message avalanches
Improper dead-letter handling can cause cascading failures:
Never use the original topic as the dead-letter topic. This creates a retry loop where dead-letter messages cycle between the original topic and failed consumption indefinitely. If the system detects that the dead-letter topic matches the original topic, the message is discarded.
Do not consume dead-letter messages with consumer groups that process normal messages. Dedicate a separate consumer group exclusively to the dead-letter topic.
Monitor dead-letter messages
Configure alert rules to detect consumption failures early and respond before dead-letter messages accumulate.
Available metrics
Source | Metric | Description |
| New dead-letter messages per minute | |
| New dead-letter messages per minute in a topic of a consumer group | |
| New dead-letter messages per minute in a consumer group | |
Consumer lag | Unconsumed dead-letter messages in the dead-letter topic | |
| Consumer lag per consumer group per topic |
Recommended monitoring approach
Detect new failures: Monitor
rocketmq_send_to_dlq_messageson the dashboard, or addSendDLQMessageCountPerGidas a CloudMonitor alert.Track unprocessed backlog: Check the Consumer lag metric on the dashboard for the dead-letter topic, or add
ConsumerLagPerGidTopicas a CloudMonitor alert.
Limitations
Dead-letter topics must use the normal message type or the ordered message type.
The original topic of a message cannot be used as the dead-letter topic. If the system detects a match, the message is discarded.
Dead-letter messages from different topics can be saved to the same dead-letter topic.
Deleting a consumer group does not delete its associated dead-letter topic.
To delete a topic associated with a dead-letter policy, disassociate the topic from the policy first.