When a consumer fails to process a message after the maximum number of retries, ApsaraMQ for RocketMQ moves the message to a dead-letter queue. Dead-letter messages typically indicate a consumer bug, a downstream dependency failure, or an incompatible message format. After you fix the root cause, resend the messages from the console for reprocessing. If you cannot resolve the issue immediately, export the messages to prevent data loss before the 3-day retention period expires. For more information about retry behavior, see Message retry.
Key characteristics
| Characteristic | Details |
|---|---|
| Scope | Each dead-letter queue belongs to a consumer group, not an individual consumer instance. All dead-letter messages from the same group land in the same queue, regardless of the original topic. |
| Creation | Created on demand. No dead-letter queue exists for a group until that group produces a dead-letter message. |
| Retention | Dead-letter messages expire after 3 days (the same retention period as normal messages). Expired messages are automatically deleted. |
| Normal delivery | Dead-letter messages cannot be consumed through normal delivery. Resend them from the console after you fix the issue. |
Diagnose dead-letter messages
When messages appear in a dead-letter queue, investigate the root cause before resending:
Check consumer logs for exceptions or errors during message processing.
Inspect the message content -- query the message by ID and review its body and properties to identify malformed or unexpected data.
Verify downstream dependencies -- confirm that databases, APIs, or other services the consumer relies on were available when the failure occurred.
Review consumer timeout settings -- make sure the consumer has enough time to process messages before they time out and trigger a retry.
Query dead-letter messages
ApsaraMQ for RocketMQ provides two query methods in the console:
| Method | Input | Match type | Best for |
|---|---|---|---|
| By group ID | Group ID + time range | Range match | Browsing all dead-letter messages in a time window |
| By message ID | Group ID + message ID | Exact match | Locating a specific message |
Steps
Log on to the ApsaraMQ for RocketMQ console. In the left-side navigation pane, click Instances.
In the top navigation bar, select a region, such as China (Hangzhou). On the Instances page, click the name of the instance that you want to manage.
In the left-side navigation pane, click Dead-letter Queues.
On the Dead-letter Queues page, select a query method:
Query by Group ID -- Specify a group ID and a time range to retrieve all matching dead-letter messages.
NoteThe generation time of a dead-letter message is when the message entered the dead-letter queue after exhausting all retries, not when it was originally sent.
Query by Message ID -- Specify a group ID and a message ID to locate a specific message.
Resend dead-letter messages
After you identify and fix the root cause, resend dead-letter messages from the console to retry consumption.
Ordered messages cannot be resent from a dead-letter queue. Export them and process them manually.
Resent messages remain stored in the dead-letter queue and are automatically deleted after the retention period expires.
Resend a single message
Query the dead-letter message using either method above.
In the message list, find the target message and click More in the Actions column.
Select Resend.
Resend multiple messages
Query dead-letter messages by group ID.
Select the messages to resend.
Click Batch Resend Messages.
Export dead-letter messages
Export messages to preserve them before the 3-day retention period expires. Exported files are in CSV format.
Export a single message
Query the dead-letter message using either method above.
In the message list, find the target message and click More in the Actions column.
Select Export Message.
Export multiple messages
Query dead-letter messages by group ID.
Select the messages to export.
Click Batch Export Messages.
Exported fields
| Field | Description |
|---|---|
| instanceId | Instance ID |
| topic | Topic the message belongs to |
| msgId | Message ID |
| bornHost | URL of the producer that produced the message |
| bornTimestamp | Timestamp when the message was produced |
| storeTimestamp | Timestamp when the broker stored the message |
| reconsumeTimes | Number of failed consumption attempts |
| properties | Message attributes in JSON format |
| body | Message body, Base64-encoded |
| bodyCRC | CRC (Cyclic Redundancy Check) value of the message body |
What to do next
Message retry -- Learn how retry intervals and maximum retry counts determine when a message becomes a dead-letter message.