Querying Dead Letter Messages
Last updated:2026-01-23 17:34:04
Scenarios
A dead letter queue is a special type of message queue that is used to centrally process messages that cannot be consumed normally. If a message still cannot be consumed normally after a certain number of retries, TDMQ for RocketMQ determines that the message cannot be consumed under the current circumstances and delivers it to the dead letter queue.
In actual scenarios, messages may fail to be consumed due to prolonged service downtime or network disconnections. In such cases, messages are not discarded immediately. The dead letter queue persists such messages for a long period. After you obtain a solution, you can create a consumer to subscribe to the dead letter queue to process such messages. You can export the messages and confirm how to process them or resend specific messages in the console.
Query Limits
Only messages within the last 3 days can be queried.
Features
After a message is delivered to the dead letter queue, it is no longer consumed normally by consumers. Only messages within the last 3 days can be queried. Try to handle these dead letter messages within 3 days after they are generated; otherwise, they may be deleted.
A dead letter queue contains all dead letter messages generated by all topics in a group. If no dead letter messages are generated in a group, no dead letter queue is created for it, and no dead letter messages can be queried.
Querying Dead Letter Messages
1. Log in to the TDMQ for RocketMQ console, and click Dead Letter Message Query in the left sidebar.
2. On the message query page, select a region and enter the query conditions as prompted.
Cluster: Select the cluster where the dead letter messages to be queried are located.
Group: Select the group where the dead letter messages to be queried are located.
Time Range: Select the time range within which you want to query messages. The options include the last 30 minutes, last 1 hour, last 6 hours, last 24 hours, and last 3 days.
Message ID: It is optional.
If you leave it blank, a fuzzy query is executed. Based on the group ID and the time range in which the dead letter messages were generated, you can batch query all the dead letter messages generated in the group within the specified period.
If you specify the message ID, an exact query is performed. Any messages can be precisely located based on the group ID and message ID.
3. Click Query. The list at the bottom of the page displays all query results with pagination.
4. You can select multiple dead letter messages and click Batch Resend Messages in the upper-left corner to resend them in batches to the retry queue of the original queue. Alternatively, you can click Resend Message in the operation column of a specific message to resend the dead letter message. After a dead letter message is resent, it is delivered to the retry queue of the original queue. It is not deleted immediately from the dead letter queue. It is deleted only after the message lifecycle (3 days) has reached.
5. Locate the message whose content or parameters you want to view, and click View Details in the operation column to view the basic information, content (message body), and parameters of the message.
6. Click View Message Trace in the operation column, or click the Message Trace tab on the details page to view the message trace of the message. (For details, see Message Trace Query Result Description.)
After dead letter messages are redelivered, the consumption status is changed to Dead Letter Redelivery Completed.
Exporting Dead Letter Messages
If you want to export all dead letter messages for separate processing, you can select the required information and click Batch Export. If you want to export a single message, click Export Message in the operation column.
The following table describes fields contained in the exported file.
Field | Description |
instanceId | Cluster ID |
group | Group to which a message belongs |
tags | Message tag |
keys | Message key |
messageId | Message ID |
bornHost | Message production address |
bornTimestamp | Message production time |
storeTimestamp | Time when a message is stored on the server |
reconsumeTimes | Number of consumption failures |
properties | Consumption property |
body | Message body |
crc | Message body cyclic redundancy check (CRC) |
Resending Dead Letter Messages
If you confirm that the code is modified, you can process the messages that were delivered to the dead letter queue after multiple consumption failures.
You can select multiple dead letter messages and click Batch Resend Messages in the upper-left corner to resend them in batches to the retry queue of the original queue. Alternatively, you can click Resend Message in the operation column of a specific message to resend the dead letter message. After dead letter messages are resent, the server delivers these messages to the retry queue of the original queue, where they can be consumed normally. The messages will not be deleted immediately from the dead letter queue and will be deleted only after reaching the end of their lifecycle (3 days).
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No
Feedback