Every MQ Reason Code

Reason code is the phrase IBM MQ practitioners use when anything numeric comes back from the product—but not every reason is MQRC. Your Java client throws MQException with reason 2035. runmqsc might show a command failure with a different numeric context. PCF automation receives reason fields in response parameters. Channel DISPLAY CHSTATUS shows LASTCHLERR text that may reference underlying reasons. Beginners who memorize only 2035 and 2085 miss the map: which subsystem produced the number, which document to open, and whether AMQERR will have a matching sentence. This page is the umbrella reference for all IBM MQ reason code types, how they relate, and where to drill down. The every-mq-mqrc-code page is the dedicated MQI encyclopedia; start here when you do not yet know which family you are holding.

Types of Reason Codes in IBM MQ

IBM MQ uses numeric reasons in several layers. MQI reason codes (MQRC) are the largest set for application developers. Completion codes (CompCode) categorize success versus failure before you interpret Reason. PCF reason codes appear in programmable command format responses used by MQ Explorer, scripts, and monitoring tools. Channel and listener subsystems may surface reason-like values in status attributes and events. Treat each layer with the same logging discipline even when the number coincidentally matches an MQRC—the producer of the code matters for documentation lookup.

Completion Code (CompCode) Explained

CompCode answers pass or fail at the API level before Reason explains why. CompCode 0 means the call completed as requested; Reason is usually 0 (MQRC_OK). CompCode 1 is warning—operation may have partially succeeded or returned advisory information; read Reason carefully because some warnings are normal (for example certain browse cases) and others precede failure. CompCode 2 is failure—the call did not achieve the requested operation; Reason holds the MQRC. Client libraries map CompCode 2 to exceptions. Never log only Reason without CompCode; some support scenarios need both to reproduce IBM documentation examples.

1
2
3
4
5
6
7
Standard application log line:
  call=MQPUT1 QM=QM1 queue=ORDERS.IN CompCode=2 Reason=2053
  meaning=put failed, queue at MAXDEPTH
 
Operator next step:
  DISPLAY QLOCAL('ORDERS.IN') CURDEPTH MAXDEPTH
  scale consumers or raise MAXDEPTH per capacity policy

MQRC: MQI Reason Codes

MQRC values are defined in cmqc.h and language bindings with symbolic names like MQRC_NOT_AUTHORIZED (2035). They cover connection, objects, authority, capacity, pub/sub, transactions, and SSL. Hundreds exist across releases; production teams standardize on twenty codes that cover most tickets. The every-mq-mqrc-code page groups them by category with actions. When Reason is 2033, ask whether GET was expected to wait; when 2059, check dspmq before OAM; when 2393, fix TLS before setmqaut.

PCF Reason Codes

Administrative interfaces using Programmable Command Format return reason codes in response structures distinct from a single MQGET call. Automation that issues MQCMD equivalents must parse PCF reason and completion fields, not assume MQRC from a different call path. Symptoms include Explorer panels failing to refresh, scripts reporting command failed with numeric code, and monitoring agents marking config deploys bad. Fix object names in the command, authority for the command issuer, and queue manager command server health. DISPLAY QMSTATUS confirms the command server is active.

Channel and Infrastructure Reasons

Channels do not always surface a clean MQRC to every observer; DISPLAY CHSTATUS shows CHSTATUS, LASTCHLERR, and state. Reason-like failures appear as RETRY, BINDING, or INACTIVE with text. Cross-reference every-mq-channel-error and every-mq-ssl-error when LASTCHLERR mentions SSL or partner not available. Sequence number mismatches after DR produce dedicated reason patterns documented in channel sequence tutorials—RESET CHANNEL is not step one without evidence.

Correlating Reason Codes with AMQ and CSQ

The same incident often produces MQRC in the app, AMQ on distributed queue managers, and CSQ on z/OS hubs. Build timelines: application millisecond, queue manager second, channel state transition. If numbers differ, they may still describe one root cause at different layers—for example TLS failure shows 2393 to a client and AMQ9638 in AMQERR without the channel reaching RUNNING.

Reason Code Lookup Workflow

1. Identify producer: MQI call, PCF command, channel status, or log only.
2. Record CompCode and Reason if MQI; record full AMQ or CSQ ID if logs.
3. Map to layer: network, TLS, CHLAUTH, OAM, object definition, capacity, app logic.
4. Open the correct reference: MQI appendix, AMQ message, CSQ message.
5. Apply one change; retest; capture before and after logs.

Similar Reason Values, Different Meaning

2033 NO_MSG_AVAILABLE is often normal on non-wait GET; 2053 Q_FULL is never normal for steady-state production. 2059 QM_NOT_AVAILABLE at connect differs from 2009 CONNECTION_BROKEN mid-session. 2085 unknown object differs from 2035 unauthorized on an existing object. Teaching support staff this table reduces misrouted tickets to the network team when the fix is DEFINE QLOCAL.

Explainer: Reason as the Fine Print

CompCode is approved or denied on the loan application. Reason is the checkbox explaining denied—insufficient funds, wrong account number, or branch closed. Same form, different checkboxes for different problems.

Explain Like I'm Five: Reason Codes

The robot gives you two numbers: one says okay or not okay, and the other says why. You need both numbers to know if you should knock again, use a different door, or ask a grown-up to fix the lock.

Practice Exercises

Exercise 1

Classify five incidents from your backlog as MQI, PCF, channel, or log-only.

Exercise 2

Write a logging standard requiring CompCode, Reason, QM, object, and API name.

Exercise 3

Link one MQRC to AMQ and one hybrid ticket to CSQ in documentation.

Frequently Asked Questions

Test Your Knowledge