MQRC reason codes are how IBM MQ tells programs what went wrong—or that nothing was wrong. Every MQCONN, MQOPEN, MQPUT, MQGET, and MQCMIT returns a completion code and, when needed, a reason code integer you can look up in documentation, log aggregators, and this reference. Developers who only print getMessage() miss the Reason that support teams need. Operators who only read AMQERR miss the 2085 the Java client saw two seconds earlier. This page is the production-focused MQRC encyclopedia entry: how to read CompCode and Reason together, categories of codes, detailed explanations of the reason codes that appear in most tickets, comparison between similar codes, and links to deep-dive tutorials on this site. IBM publishes the exhaustive list per release; we teach the patterns so you are not memorizing three hundred numbers—you are recognizing families.
On a successful MQPUT, CompCode is 0 and Reason is MQRC_OK (0). On failure, CompCode is typically 2 and Reason carries the specific MQRC—for example 2053 when the queue is full. Warnings use CompCode 1 with a non-zero Reason depending on call. Client libraries throw exceptions that wrap the same integers. Always record the API name, object name, queue manager name, and channel if remote. A GET that returns 2033 with CompCode 2 is often normal empty queue behavior when no wait was requested; the same 2033 with wait and timeout may be expected idle consumer behavior—not an incident.
1234Log line template for developers: API=MQOPEN QM=QM1 Object=ORDERS.IN QType=local CompCode=2 Reason=2035 (MQRC_NOT_AUTHORIZED) EffectiveUser=mqmapp (from channel MCAUSER if remote)
These codes appear on MQCONN, MQCONNX, or when the queue manager is unavailable during any call.
| MQRC | Name | Meaning | Typical action |
|---|---|---|---|
| 2009 | CONNECTION_BROKEN | Connection to QM lost mid-call | Check network, QM restart, firewall; reconnect app |
| 2059 | QM_NOT_AVAILABLE | Cannot connect to QM | dspmq; strmqm; verify host and port in MQSERVER |
| 2058 | Q_MGR_NAME_ERROR | Wrong queue manager name | Match crtmqm name and connection string |
| 2161 | QM_STOPPING | QM in quiesce or shutdown | Wait for maintenance end or use alternate QM in HA |
Object errors mean the name in MQOD does not resolve to an accessible definition on the queue manager you reached—not necessarily that the queue never existed anywhere in the enterprise.
| MQRC | Name | Meaning | Typical action |
|---|---|---|---|
| 2085 | UNKNOWN_OBJECT_NAME | Queue or topic not defined on this QM | DISPLAY QLOCAL; cluster REFRESH; fix typo |
| 2082 | UNKNOWN_ALIAS_BASE_Q | Alias points to missing base | DISPLAY QALIAS TARGQ; DEFINE base |
| 2087 | UNKNOWN_OBJECT_Q_MGR | Remote QM name wrong on QREMOTE | DISPLAY QREMOTE RQMNAME |
| 2110 | OBJECT_ALREADY_EXISTS | DEFINE without REPLACE on existing | ALTER or DEFINE REPLACE per policy |
Authority failures happen after connect in many cases—the channel shows RUNNING but MQOPEN fails. Grant minimum +connect +put or +get via setmqaut for the MCAUSER or application ID actually in use.
| MQRC | Name | Meaning | Typical action |
|---|---|---|---|
| 2035 | NOT_AUTHORIZED | OAM or SAF denied operation | dspmqaut; CHLAUTH MCAUSER; see 2035 tutorial |
| 2063 | NOT_AUTHORIZED_FOR_CONN | Cannot connect as this user | CONNAUTH; CHLAUTH; connect authority |
| 2393 | SSL_INITIALIZATION_ERROR | TLS setup failed | Keystore, cipher, cert expiry |
| 2397 | SSL_NOT_ALLOWED | Policy requires TLS; plain used | SSLCIPH on channel; client TLS |
Capacity codes reflect MAXDEPTH, message length limits, and whether a message exists for GET.
| MQRC | Name | Meaning | Typical action |
|---|---|---|---|
| 2053 | Q_FULL | CURDEPTH at MAXDEPTH | Scale consumers; raise MAXDEPTH; back pressure |
| 2014 | MSG_TOO_BIG_FOR_Q | Message exceeds MAXMSGL | ALTER MAXMSGL or shrink payload |
| 2033 | NO_MSG_AVAILABLE | No message for GET | Normal if empty; check producer |
| 2071 | MSG_TOO_BIG_FOR_CHANNEL | Exceeds channel MAXMSGL | ALTER channel MAXMSGL both sides |
Transactional applications see these during commit, rollback, and backout threshold handling.
| MQRC | Name | Meaning | Typical action |
|---|---|---|---|
| 2024 | SYNCPOINT_LIMIT_REACHED | Too many UOW branches | Commit more often; review app logic |
| 2025 | SYNCPOINT_NOT_AVAILABLE | QM or object not syncpoint capable | Check QM and queue attributes |
| 2017 | MSG_MARKED_BROWSE_COOPERATION | Browse mark in use | Reset browse or close handle |
| 2192 | BACKOUT_THRESHOLD_REACHED | Poison message backout count hit | Fix consumer; check BOQNAME DLQ |
Pub/sub failures add topic string and subscription scope to your log template.
2059 versus 2009: 2059 is cannot establish or QM unavailable at connect; 2009 is had connection then lost it. 2085 versus 2035: 2085 is unknown name; 2035 is name exists but user cannot access. 2033 versus 2053: 2033 is no message to get; 2053 is cannot put because queue full. 2393 versus CHLAUTH block: TLS fails at handshake; CHLAUTH may never show RUNNING. Teaching teams this distinction cuts mean time to repair.
Wrap MQI in a company logging helper that translates Reason to a short enum for dashboards while preserving the integer for support. Alert on rate of 2053 per queue. Suppress alert noise on 2033 for idle consumers with wait. Never alert on 2033 alone without queue name and consumer identity context.
CompCode is pass or fail on the form. Reason is the checkbox explaining why—wrong desk, building closed, mailbox full, or no mail yet.
When you ask the mail robot for a letter, it hands you a number. Zero means here is your letter. Other numbers mean try another mailbox, you are not allowed, or the building is closed.
Provoke 2053, 2035, and 2085 in lab; fill in the log template for each.
From one AMQERR excerpt, identify which MQRC the application likely received.
Build a team cheat sheet of ten MQRC codes with one-line fixes.
1. MQRC_OK equals:
2. CompCode 2 with Reason 2085 means:
3. 2059 often means:
4. 2033 on GET means: