2059 Errors

Reason code 2059—MQRC_Q_MGR_NOT_AVAILABLE—means the application never got a working conversation with the queue manager it asked for. The client library called MQCONN or MQCONNX with a name like QM_PROD, and the infrastructure underneath said that queue manager is not here or not accepting work. Beginners see 2059 and increase MAXDEPTH; veterans check dspmq, the listener, and whether the name in mqclient.ini matches the instance that actually started after last night failover. 2059 appears during cold starts, wrong-environment configuration files, firewall changes, and planned quiesce windows. This tutorial separates 2059 from 2538 and 2009, walks through distributed and z/OS checks, documents listener and channel prerequisites, and gives a repeatable runbook operators can execute in five minutes before escalating to application teams.

When Clients See 2059

MQCONN and MQCONNX return 2059 when the queue manager process is not in RUNNING state, the name does not match any instance on the host, or the client channel path cannot complete queue manager handshake—sometimes because the listener is down even though dspmq shows RUNNING. JMS ConnectionFactory creation failures often wrap 2059 in a generic JMSException; always unwrap to MQ reason in logs. Batch jobs using server bindings fail 2059 when the local queue manager was not started by init scripts after reboot.

Distributed Troubleshooting Runbook

1. On server: dspmq -m QMNAME — status RUNNING?
2. If not RUNNING: inspect AMQERR, disk space, strmqm manual start.
3. DISPLAY LSSTATUS for listener on client CONNAME port.
4. From client host: telnet or openssl s_client to host port—not from laptop only.
5. Verify client QM name, channel, CONNAME in mqclient.ini or CCDT.
6. Check recent quiesce or failover—did automation start standby QM with different name?

1
2
3
4
5
6
dspmq -m QM_PROD
DISPLAY LSSTATUS(LISTENER.TCP) ALL
START LISTENER(LISTENER.TCP)
* After storage incident:
df -h /var/mqm
strmqm QM_PROD

Multi-Instance and Failover

Active/standby queue managers may expose the same logical name on virtual IP. If failover lags, clients see 2059 until standby becomes active and listeners bind. Client reconnection attributes help only after the standby is actually RUNNING—tune HA scripts and health checks before blaming applications. Document expected 2059 duration during controlled switchover.

z/OS

MQ subsystem not started, SMFID mismatch, or queue manager not active in the sysplex shows as unavailable to remote TCP clients and to local attach depending on configuration. Use operations procedures for START MQ and display subsystem status. Coupling facility recovery may delay availability—coordinate with systems programming.

Application Configuration Mistakes

• QM_PROD in code but QM_PROD_TEST in container environment variable.
• CCDT pointing to decommissioned host after datacenter migration.
• Kubernetes service name wrong namespace—DNS resolves but not to MQ pod.
• Bindings mode job on host without local QM—should use client connection instead.

Explainer: Calling a Closed Store

2059 is dialing a store whose lights are off—the phone network works (maybe), but nobody is open to take your order at that brand name.

Explain Like I'm Five: 2059 Errors

You shouted hello to the marble bank by its name, but that bank is closed or you used the wrong name—so nobody answered.

Practice Exercises

Exercise 1

Write ordered checks for 2059 versus 2538 in a table with expected outcome per step.

Exercise 2

List three HA scenarios where 2059 is expected briefly and how clients should handle it.

Exercise 3

Simulate wrong QM name in mqclient.ini and document exact client log lines.

Frequently Asked Questions

Test Your Knowledge