Defining Dead Letter Queues

The dead letter queue (DLQ) is the safety net when IBM MQ cannot deliver a message to its intended destination, or when configuration routes failed messages for operator attention. Unlike a transmission queue or remote queue definition, the DLQ is a real local queue that stores messages—often with an extra dead-letter header describing what went wrong. This tutorial focuses on how to define and wire that queue: CREATE the QLOCAL, point the queue manager with DEADQ, tune MAXDEPTH and security, distinguish DLQ from backout queues, and operate a healthy DLQ process. If you already read the conceptual dead letter tutorial, this page is the hands-on companion for administrators promoting environments from lab to production.

Default SYSTEM.DEAD.LETTER.QUEUE

Many installations use the default name SYSTEM.DEAD.LETTER.QUEUE created at queue manager creation. DISPLAY QLOCAL(SYSTEM.DEAD.LETTER.QUEUE) shows whether it exists and its attributes. DISPLAY QMGR DEADQ shows whether the queue manager references it. If DEADQ is blank, dead-lettering may not occur when required—verify your platform defaults in IBM documentation for your release. Custom names such as DLQ.MONITOR or DEAD.LETTER.PROD are common in enterprises that segregate environments or feed centralized monitoring tools.

Step-by-Step: Define and Assign DEADQ

1. DEFINE QLOCAL for the DLQ with production MAXDEPTH, MAXMSGL, DEFPSIST(YES), GET/PUT enabled for handlers.
2. ALTER QMGR DEADQ('your.dlq.name') to bind the queue manager.
3. Grant authority to operations and DLQ handler applications (GET, PUT, INQ as needed).
4. DISPLAY QMGR DEADQ and DISPLAY QLOCAL to confirm.
5. Document runbooks: who reads DLQ, how to requeue after fix, when to discard.

1
2
3
4
5
6
7
8
9
DEFINE QLOCAL('DLQ.MONITOR') REPLACE +
  MAXDEPTH(100000) +
  MAXMSGL(4194304) +
  DEFPSIST(YES) +
  GET(ENABLED) PUT(ENABLED) +
  DESCR('Central dead letter - Ops team')
ALTER QMGR DEADQ('DLQ.MONITOR')
DISPLAY QMGR DEADQ
DISPLAY QLOCAL('DLQ.MONITOR') ALL

DEADQ vs Backout Queue (BOQNAME)

When an application MQGETs a message and rolls back repeatedly (backout count increases), MQ can move the message to the backout queue named in BOQNAME on that application queue—if configured. That path is about poison messages and consumer failure. DEADQ handles queue-manager-level dead lettering: expiry, message too big for target, put to unknown object in some cases, and similar reason codes described in IBM MQ reason code documentation. A payment queue might have BOQNAME(PAYMENTS.BACKOUT) for bad XML, while the queue manager DEADQ catches routing failures. Operators need both monitors in mature estates.

Reading the Dead-Letter Header (MQDLH)

Messages on the DLQ frequently include an MQDLH structure before the original data. Fields such as Reason, DestQ, DestQMgr, PutApplName, and PutDate tell you the intended target and why dead-lettering occurred. Reason 2085 might mean unknown object; other codes point to expiry or length limits. Support teams map Reason to corrective action: fix typo in queue name, increase MAXMSGL, extend expiry, or restart a channel. Requeue tools strip or preserve headers depending on design—beginners should practice on a lab DLQ before touching production.

Attributes to Set on the DLQ QLOCAL

• MAXDEPTH — cap growth; alert before full so new dead letters are not lost.
• MAXMSGL — must accept largest message plus DLH overhead on your platform.
• DEFPSIST(YES) — dead letters are usually audit-relevant; survive restart.
• GET/PUT — handlers need GET; some requeue flows need PUT.
• DESCR — document owner, ticket queue, and retention policy.
• Not USAGE(XMITQ) — DLQ is NORMAL usage; do not confuse with transmission queues.

Security and Compliance

DLQ messages may contain failed payment payloads, PII, or credentials in error dumps. Restrict GET authority to break-glass roles and automated handlers. Log access for compliance. In regulated industries, retention and purge schedules apply to DLQ depth as they do to business queues. Masking in logs when displaying DLH contents in tickets reduces exposure.

DLQ Handlers and Operations

A DLQ handler is any process that monitors CURDEPTH, parses MQDLH, alerts, and optionally requeues after fix. Manual runbooks work at small scale: amqsget or MQ Explorer browse, fix root cause, put to corrected queue. Larger shops use IBM or third-party tools and idempotent requeue applications. Never clear a DLQ blindly in production without understanding whether messages are legally required records of failed transactions.

Testing Dead Lettering in a Lab

1
2
3
4
5
6
* Force unknown remote target (lab only):
DEFINE QREMOTE('LAB.BAD') REPLACE +
  RNAME('DOES.NOT.EXIST') RQMNAME('QM_FAKE') +
  XMITQ('SYSTEM.DEFAULT.XMIT.QUEUE')
* Put may eventually dead-letter depending on config;
* DISPLAY QLOCAL(DLQ) CURDEPTH and browse for MQDLH

Safer lab tests use explicit report options or known reason paths documented for your release. Always test on disposable queue managers. After test, purge lab DLQ and remove bad definitions.

Explain Like I'm Five: Dead Letter Queue

Sometimes the post office cannot deliver your letter—wrong address, house gone, or letter too big for the mailbox. Instead of throwing it away silently, they put it in a special box labeled “could not deliver” (dead letter queue). A grown-up reads the sticker on the letter (dead-letter header) to see what went wrong and whether to try again.

Practice Exercises

Exercise 1

Write MQSC to create DLQ.PROD and set it as DEADQ. List three DISPLAY commands to verify.

Exercise 2

Explain to a developer why poison messages might land on BOQNAME but not DEADQ.

Exercise 3

DLQ CURDEPTH doubled after a channel outage. Is that always a DLQ problem? What else could cause it?

Frequently Asked Questions

Test Your Knowledge