"We have a message stuck on MQ" is one of the vaguest—and most urgent—tickets operations receives. The message may be on an application queue with no consumer, on a transmission queue while a channel retries, inside an uncommitted transaction, or cycling through backout without completing. Beginners browse the queue and delete messages; experienced teams classify where the message is stuck in the pipeline, whether it is visible or in-doubt, and whether movement is blocked by depth, authority, or application logic. This tutorial explains stuck message scenarios, how syncpoint and UOW affect visibility, diagnosing with DISPLAY QSTATUS and CHSTATUS, safe browse and move options, coordination with application teams, and prevention through monitoring depth and consumer health.
Messages flow: producer MQPUT → queue → consumer MQGET → processing → commit. Interruption at any step leaves work incomplete. Distributed flows add remote queue, XMITQ, channel, partner queue manager, and partner application. A message reported stuck in Paris may actually be blocked on London XMITQ. Always confirm queue manager name, queue name, and MSGID when starting triage.
| Location | Typical cause | First action |
|---|---|---|
| Application QLOCAL | Consumer down or slow | Check OPPROCS, restart app |
| XMITQ | Channel not RUNNING | DISPLAY CHSTATUS, fix channel |
| Uncommitted UOW | Crashed app before commit | Resolve in-doubt, rollback/commit |
| Backout loop | Poison message | BOTHRESH, DLQ, fix app |
When applications use syncpoint, puts and gets are part of a unit of work. Until MQCMIT, other programs may not see puts on the queue (depending on isolation). If the application terminates abnormally, the transaction manager and queue manager may leave the UOW in-doubt—neither fully committed nor rolled back. In-doubt resolution uses platform tools (dspmqtrn on distributed, or z/OS recovery procedures). Do not clear the queue blindly while in-doubt work exists—coordinate with the transaction manager team and application owners.
DISPLAY QSTATUS('PAY.IN') CURDEPTH IPPROCS OPPROCS shows depth and open handles. CURDEPTH greater than zero with OPPROCS zero means no getter is active—batch job not started, CICS transaction stopped, Kubernetes pod crashed. IPPROCS without OPPROCS may mean a browser or poison consumer holding the queue open. Check application logs at the same timestamp depth started rising. Triggered queues need trigger monitor running and valid PROCESS definition—depth grows if trigger never fires.
1234DISPLAY QSTATUS('PAY.IN') CURDEPTH IPPROCS OPPROCS DISPLAY QLOCAL('PAY.IN') TRIGGER TRIGTYPE TRIGDATA PROCESS DISPLAY CHSTATUS('TO.PARTNER') STATUS DISPLAY QSTATUS('SYSTEM.XMIT.QUEUE') CURDEPTH
Messages on XMITQ are not stuck in the sense of corruption—they await transmission. If STATUS is RETRY or INACTIVE, fix channel, TLS, or network per channel retry loop runbooks. If RUNNING but depth not falling, investigate batch size, channel throughput, or partner receiver not committing. Sequence number issues can stall committed delivery while depth appears static on one side.
Browse (where policy allows) inspects message headers and payload without removing—useful to confirm poison format. Moving messages to a backout or DLQ requires authority and change approval. ALTER queue BOTHRESH and BOQNAME route poison messages after repeated backout. Manual move with MQ tools is a last resort for single messages after business sign-off—not bulk CLEAR QLOCAL without understanding impact.
A stuck message is a package sitting on a conveyor belt segment. The belt before it worked; the belt after may be stopped. You find which segment holds the box—application queue, loading dock (XMITQ), or still in the warehouse office (uncommitted)—before you throw the box away.
A letter is in the mailbox but nobody takes it out to read it, or the mail truck cannot drive to the next town. The letter is not broken—the delivery path is.
Lab: stop consumer with messages on queue; document QSTATUS fields that prove no getter.
Diagram message path for QREMOTE across two QMs; mark where stuck reports could mean each segment.
Write escalation template: MSGID, depth, OPPROCS, channel status.
1. Message on XMITQ not moving often needs:
2. Uncommitted UOW messages are invisible to:
3. OPPROCS zero with rising CURDEPTH suggests:
4. Poison message may appear stuck because: