Backout Queues

A backout queue is your safety valve when application processing fails repeatedly. While BOTHRESH and BOQNAME are individual attributes, the backout queue usage pattern is how operations and developers work together: design paired queues, monitor backout depth, triage poison payloads, fix defects, and requeue safely. Without a dedicated backout queue, one bad message blocks a work queue; with a sloppy backout process, bad data is requeued twice and posts duplicate payments. This page walks through naming, MQSC definitions, runbooks, differences from the dead-letter queue, JMS poison handling, and requeue discipline for beginners.

Pattern: Work Queue Plus Backout Queue

ORDERS.IN is the work queue with BOTHRESH(3) BOQNAME('ORDERS.BO'). ORDERS.BO is a normal local queue (USAGE NORMAL) sized for incident volume. Consumers only get from ORDERS.IN in steady state. ORDERS.BO is read by support tools or a controlled repair program after human approval. Naming symmetry (.IN / .BO) helps on-call engineers find pairs in MQSC exports at 3 a.m.

Lifecycle of a Poison Message

1. Message put to work queue with BackoutCount 0.
2. Consumer gets under syncpoint; processing fails; MQBACK increments BackoutCount.
3. Retries until BackoutCount reaches BOTHRESH.
4. Queue manager moves message to BOQNAME queue instead of redelivering to app.
5. Operations analyze payload, fix code or data, requeue or purge with audit.

Defining Backout Queues in MQSC

1
2
3
4
5
6
DEFINE QLOCAL('ORDERS.BO') REPLACE MAXDEPTH(20000) +
  DEFPSIST(YES) GET(ENABLED) PUT(ENABLED) +
  DESCR('Backout for ORDERS.IN - no BOQNAME here')
ALTER QLOCAL('ORDERS.IN') BOTHRESH(3) BOQNAME('ORDERS.BO')
DISPLAY QLOCAL('ORDERS.IN') BOTHRESH BOQNAME
DISPLAY QLOCAL('ORDERS.BO') CURDEPTH

Operations Runbook

Alert when CURDEPTH on any *.BO queue is greater than 0. On alert: capture MQMD (MsgId, CorrelId, BackoutCount), application logs, and message body (redact PII in tickets). Identify if defect is code deploy, bad vendor file, or data. Fix forward. Requeue using supported tools (amqsbcg samples, custom program with audit, or IBM MQ Explorer) only after root-cause sign-off. Document count requeued. If message is permanently invalid, archive and delete per retention policy—not silent purge.

Backout vs Dead-Letter Queue

Backout is deliberate application-level poison isolation. DLQ catches MQ routing failures, expired messages, and puts that fail including failed put to backout. Your runbook should list both. Teams that only monitor DLQ miss poison solely on ORDERS.BO. Teams that requeue DLQ messages without analysis repeat enterprise incidents.

Requeue Risks

• Requeue without fix—message returns to BOQNAME again.
• BackoutCount still high—may immediately re-backout; understand reset behavior.
• Duplicate business effect if first attempt partially committed downstream.
• Wrong target queue—always verify queue name in change record.

Multiple Application Queues

Each critical work queue can point to its own backout queue (PAYMENTS.BO, INVENTORY.BO) or share one department backout queue—shared simplifies monitoring but mixes payloads. High-security flows often isolate backout per queue for clearer ownership. Never point many unrelated flows to one backout queue without labeling in message headers.

JMS and .NET Clients

Enable poison message handling per client documentation so BOTHRESH and BOQNAME are honored on rollback. Session transacted mode is required for meaningful backout counting. Unit tests should include one poison message and assert arrival on BO after threshold.

Explain Like I'm Five: Backout Queue

The class line has a broken toy that stops everyone. After three failed tries, the teacher moves that toy to a side table (backout queue) so the line keeps moving. Adults fix the toy later at the side table.

Practice Exercises

Exercise 1

Write a one-page runbook outline for ORDERS.BO depth alert.

Exercise 2

Why should ORDERS.BO not have BOQNAME('ORDERS.BO')?

Exercise 3

Message on DLQ after backout—name two possible causes.

Frequently Asked Questions

Test Your Knowledge