MQRC 2538: Host unavailable

What it means

A client connects by opening a TCP connection to the host and port in its channel definition, where a queue manager listener should be waiting. 2538 means that step failed. The client never got as far as talking to the queue manager, so nothing about authority, channel names or queue manager names has been checked yet.

IBM lists five causes. The listener isn't running. The connection name (host and port) is wrong. The network is down. A firewall blocks the port or protocol. Or a security exit on the server-connection channel blocks the call that sets up the client. IBM also points out that on Linux servers the host's own firewall can be the cause.

The client error log usually holds the useful detail, with the host, the port and the operating system's TCP return code, such as connection refused or timed out. Refused means something on that host answered and nothing was listening on the port. A timeout means a firewall or routing problem is more likely. On z/OS queue managers the listener runs in the channel initiator, so the CHIN address space must be up with a TCP listener started.

Common causes

• The queue manager's listener isn't running, or it listens on a different port from the one the client uses.
• The host name or port in MQSERVER, the CCDT, the connection factory or the connection name list is wrong or out of date, for example after a server move.
• A firewall, either on the network or on the server itself, blocks the port.
• DNS resolves the host name to the wrong address, or not at all.
• On z/OS, the channel initiator isn't running or has no TCP listener started on that port.

How to find the problem

1. Read the client error log (AMQERR01.LOG in the client's errors directory). Look for AMQ9202E or a similar message naming the host, port and TCP return code.
2. On the server, check the listener with DISPLAY LSSTATUS(*) in runmqsc. On z/OS, use DISPLAY CHINIT to see the listeners running in the channel initiator.
3. Test the port from the client machine with a simple TCP connection test. If it fails, the problem is network or firewall, not MQ.
4. Check the exact connection name the application uses. Connection name lists try each address in turn, so check every entry.

How to fix it

• Start the listener. On distributed MQ define it with CONTROL(QMGR) so it starts with the queue manager, or start it with START LISTENER(...). On z/OS, use START LISTENER TRPTYPE(TCP) PORT(1414) in the channel initiator.
• Correct the host and port in the client configuration.
• Open the port on network and host firewalls between the client and the queue manager.
• If the queue manager can move between hosts, list every address in the connection name, or use a CCDT, so the client can find it.

What it looks like

JMSWMQ0018: Failed to connect to queue manager 'QM1' with connection mode 'Client' and host name 'mqhost01(1414)'.
JMSCMQ0001: IBM MQ call failed with compcode '2' ('MQCC_FAILED') reason '2538' ('MQRC_HOST_NOT_AVAILABLE').

Technical reviewer: Albert Joseph, WND Software.

Last reviewed 2026-10-18 by the WND Software team. Written in our own words. For the full reference, check IBM’s MQ documentation for your version.