BOQNAME holds the name of your backout queue—the parking lot for poison messages that your application could not process successfully after several tries. Without a named backout queue, a bad XML fragment or wrong database key can spin forever: get, fail, rollback, get again, blocking healthy messages behind it. BOQNAME together with BOTHRESH gives IBM MQ a controlled exit path so operators can inspect, repair, and requeue bad data while the main work queue keeps flowing. This page explains how BOQNAME works with syncpoint rollback, BackoutCount in the MQMD, differences from the dead-letter queue, how to define backout queues in MQSC, and operational practices beginners need before enabling backout in production.
A poison message is valid for MQ—it put successfully—but semantically wrong for your program: schema mismatch, unknown account number, or code bug that always throws. Under syncpoint, the consumer MQGETs under syncpoint, processing fails, MQBACK rolls back, and the message becomes visible again with BackoutCount incremented. Without BOTHRESH and BOQNAME, the same message may be redelivered indefinitely while your error logs repeat. Setting BOQNAME('ORDERS.BO') tells the queue manager: after enough backouts, move this message to ORDERS.BO so other messages on ORDERS.IN can be processed.
BOTHRESH is the numeric limit; BOQNAME is the destination. Example: BOTHRESH(3) and BOQNAME('ORDERS.BO')—on the fourth failure path (when BackoutCount meets threshold per IBM rules for your API), MQ routes to the backout queue instead of delivering to the application again. JMS and .NET clients follow the same conceptual model documented for poison handling. Always set both; BOQNAME alone with BOTHRESH(0) leaves protection disabled.
| Path | What drives it | Typical owner |
|---|---|---|
| Backout queue (BOQNAME) | Application rollback; BackoutCount vs BOTHRESH | Application team |
| Dead-letter queue (DEADQ) | MQ cannot deliver, unknown object, expiry, etc. | Middleware / ops |
| Still on app queue | BOTHRESH not exceeded yet | App retries with idempotency |
Create a local queue for backout traffic—often named with a .BO or .BACKOUT suffix matching the application queue. Grant put and get appropriately for operators and repair jobs. Do not point the backout queue's BOQNAME at itself. MAXDEPTH should accommodate worst-case poison bursts during a bad deploy (every message failing once). DEFPSIST(YES) is common so poison payloads survive restarts for forensic analysis. Monitor CURDEPTH on backout queues with high-severity alerts: any message there is a production incident waiting for triage.
123456DEFINE QLOCAL('ORDERS.BO') REPLACE MAXDEPTH(50000) + DEFPSIST(YES) DESCR('Backout for ORDERS.IN') GET(ENABLED) PUT(ENABLED) DEFINE QLOCAL('ORDERS.IN') REPLACE + BOQNAME('ORDERS.BO') BOTHRESH(3) MAXDEPTH(500000) DISPLAY QLOCAL('ORDERS.IN') BOQNAME BOTHRESH * After fix: move messages from ORDERS.BO back to ORDERS.IN with care
MQ moves messages to BOQNAME when threshold is met; applications should still log the failure reason before rollback and use idempotent processing where redelivery happens below threshold. Some teams MQINQ BackoutCount and proactively skip to DLQ or BOQNAME in code—usually unnecessary if BOTHRESH is set correctly. After fixing code or data, use the MQ requeue tools or a controlled program to move messages from BOQNAME to the work queue, resetting or accepting BackoutCount per your runbook. Never blindly requeue without understanding why poison occurred.
The queue manager DEADQ catches messages MQ itself cannot handle—unknown remote queue, message too big for target, expiration, or failed put to BOQNAME. Application teams own BOQNAME content and root-cause analysis; operations often own DLQ depth and routing rules. A mature estate documents both runbooks. Reporting should tag whether an incident started on application queue, backout queue, or DLQ to avoid teams talking past each other.
IBM MQ classes for JMS honor BOTHRESH and BOQNAME on the underlying queue when poison message handling is enabled in the client configuration. Developers still configure session transacted mode and rollback on failure. Test poison scenarios in integration: put a known-bad message, confirm it lands on BOQNAME after threshold, confirm good messages continue. Automate this test in CI when possible.
Backout queues may hold PCI or PII payloads that failed validation—restrict GET authority to break-glass roles. Audit who drained BOQNAME and whether messages were deleted or requeued. Retention policies may require moving backout messages to archive storage before PURGE. BOQNAME is not a “trash” queue; it is evidence during incidents.
A broken toy keeps getting sent on the conveyor belt and jamming everyone. BOQNAME is a side table where the broken toy goes after three failed repair attempts (BOTHRESH), so the good toys keep moving. Grown-ups fix the toy at the side table later.
Write DEFINE commands for ORDERS.IN with BOTHRESH(5) and BOQNAME ORDERS.BO including a safe ORDERS.BO definition.
A message is on BOQNAME. List four pieces of information you would gather before requeueing.
Explain to a teammate why BOQNAME is not a substitute for fixing application bugs.
1. BOQNAME identifies:
2. Messages move to BOQNAME when BackoutCount:
3. Backout queue definitions should usually:
4. Backout differs from DLQ because: