Dead Letter Queues

Dead letter queues are IBM MQ's safety net for messages that cannot complete their journey—wrong destination, expired lifetime, queue full, or policy-driven rejection. Instead of vanishing silently, the message lands on the DLQ with a dead-letter header explaining the problem. Operations teams live on the DLQ during migrations; developers learn reason codes when a test put never arrives. This page covers DEADQ configuration, SYSTEM.DEAD.LETTER.QUEUE, the MQDLH structure and common Reason values, relationship to backout queues and poison messages, browsing and requeue discipline, channel and XMITQ failures, z/OS considerations, and runbooks beginners can follow when depth on the DLQ spikes at 2 a.m.

Queue Manager DEADQ

ALTER QMGR DEADQ names the local queue that receives dead-lettered messages. DISPLAY QMGR DEADQ shows the current setting. If dead-lettering is disabled (no DEADQ), some failures return errors to the application without a DLQ copy—know your default on new queue managers. Production estates almost always set a DLQ and monitor its depth. Custom names like DLQ.BUSINESS or per-environment DLQ.OPS help routing alerts.

Anatomy of a DLQ Message

The message body often begins with the MQDLH structure followed by all or part of the original message. DestQ and DestQMgr show where the message was headed. Original MsgId may appear in the embedded MQMD within the payload. Tools and scripts strip the header for analysis. Never requeue blindly: fix MAXDEPTH, create missing queues, extend MAXMSGL, or correct channel paths first.

DLQ vs Backout Queue

Backout queue (BOQNAME) holds messages that exceeded BOTHRESH on application backout—consumer could not process. DLQ holds broader routing and policy failures. A poison message might visit backout queue first, then DLQ if configured. Architects document both paths in the same runbook section. Poison message tutorial follows this one in the learning track.

Expiration and Message Lifetime

Expiry in MQMD limits how long a message remains deliverable. When expiry elapses, the message may be discarded or dead-lettered depending on report options and queue manager handling. Long backlog during outage can cause mass expiry to DLQ when processing resumes—plan expiry values longer than worst-case outage or accept DLQ replay work.

Channel and Transmission Failures

Messages stuck on XMITQ may eventually trigger operational procedures; not every channel problem sends to DLQ automatically. Partner queue full on the remote side can dead-letter after retry policies. Include DLQ depth in channel incident dashboards when cross-site traffic fails.

Operations Runbook

1. Alert on DLQ CURDEPTH above baseline.
2. Browse message; record MQDLH Reason, DestQ, MsgId hex.
3. Fix configuration (queue exists, MAXMSGL, authority, channel).
4. Requeue with approved tool or application—test in lower environment first.
5. Post-incident: tune expiry, depth, or consumer to prevent repeat.

Tutorial: MQSC for DLQ Awareness

1
2
3
4
5
6
DISPLAY QMGR DEADQ
DISPLAY QLOCAL('SYSTEM.DEAD.LETTER.QUEUE') CURDEPTH MAXDEPTH
* Browse DLQ message (interactive tool or amqbcgbc)
* Read DLH Reason and DestQ before requeue
ALTER QMGR DEADQ('SYSTEM.DEAD.LETTER.QUEUE')
DEFINE QLOCAL('DLQ.MONITOR') REPLACE MAXDEPTH(100000)

Explain Like I'm Five: Dead Letter Queue

The post office could not deliver your letter because the address did not exist. Instead of throwing it in the trash, they put it in a special bin labeled could not deliver with a note why. The dead letter queue is that bin; the note on the envelope is the dead-letter header.

Practice Exercises

Exercise 1: Reason Code

DLH shows Q_FULL for ORDERS.IN. List three fixes and one monitoring improvement.

Exercise 2: Requeue Risk

Operator requeues 10,000 DLQ messages without fixing MAXMSGL. What happens?

Exercise 3: Design

Should each application have its own DLQ or one central DLQ? Argue both sides briefly.

Frequently Asked Questions

Test Your Knowledge