Let's say the following error occurs when attempting to connect to the queue manager named MANAGER01.

JMSWMQ0018: Failed to connect to queue manager 'MANAGER01' with connection mode 'Client' and host name 'server1.example.com(1414)'.

Following this message, there should be another message that may help to determine why the connection has failed.

JMSCMQ0001: WebSphere MQ call failed with compcode '2' ('MQCC_FAILED') reason '2538' ('MQRC_HOST_NOT_AVAILABLE').

DNS

Use the nslookup command to ensure DNS is able to resolve the host name to the correct MQ server.

nslookup server1.example.com

On the MQ server, use the dspmq command to ensure the queue manager is running. If the queue manager is not running, use the strmqm command to start the queue manager.

QMNAME(MANAGER01)    STATUS(Running)

Queue Manager Listener Port and Status

Use the display lsstatus command to ensure the queue manager listener is running and is using the port identified in the error message.

~]# echo "display lsstatus (*) all" | runmqsc MANAGER01
STATUS(RUNNING)
PORT(1414)

Clustered queue managers

Let's say you have 2 queue managers, where the queue manager exists on both server1.example.com and server2.example.com, running as primary on either server1 or server2 and running as standby on the other server. In this scenario, you will want to determine the datetime that the client got MQRC_HOST_NOT_AVAILABLE. 

The queue managers AMQERR01.log should have something like this when the queue manager was started as primary. Notice in this example, MANAGER01 is the primary on server1.example.com.

04/24/2022 02:15:21 AM - Process(1745.1) User(mqm) Program(amqzxma0)
                    Host(server1.example.com) Installation(Installation1)
                    VRMF(9.1.0.10) QMgr(MANAGER01)
                    Time(2022-04-24T07:15:21.395Z)
                    CommentInsert3(MANAGER01)

AMQ8352I: IBM MQ queue manager 'MANAGER01' becoming the active instance.

The queue managers AMQERR01.log on the other server (server2.example.com in this example) should have the following.

04/24/2022 02:15:21 AM - Process(1745.1) User(mqm) Program(amqzxma0)
                    Host(server2.example.com) Installation(Installation1)
                    VRMF(9.1.0.10) QMgr(MANAGER01)
                    Time(2022-04-24T07:15:21.395Z)
                    CommentInsert3(MANAGER01)

AMQ8060I: IBM MQ queue manager 'MANAGER01' started as a standby instance.

In this scenario, if the client attempts to connect to the queue manager running as standby, MQRC_HOST_NOT_AVAILABLE can be returned.

Channel

Use the display chlauth command to determine if the channel has been granted authority. If the display chlauth command returns "channel authentication record not found", use the set chlauth command to give the channel authority. If the display chlauth command returns somelike like this, and type is ADDRESSMAP, only requests coming from the IP address or hostname listed in ADDRESS will be permitted to connect to the channel.

echo "display chlauth (CHANNEL01)" | runmqsc MANAGER01

CHLAUTH(CHANNEL01)                      TYPE(ADDRESSMAP)
DESCR(Allow access and use ID from channel)
CUSTOM( )                               ADDRESS(10.15.55.*)
USERSRC(CHANNEL)                        CHCKCLNT(ASQMGR)
ALTDATE(2019-08-20)                     ALTTIME(07.09.01)

The dspmqaut command can be used to ensure the user has the appropriate permissions to the queue manager.

dspmqaut -m MANAGER01 -t qmgr -p JohnDoe

Entity JohnDoe has the following authorizations for object MANAGER01: 
    connect
    inq

Use the display channel command to determine if the channel expects a certain SSL cipher.

echo "display channel (CHANNEL01)" | runmqsc MANAGER01

Something like this should be returned.

CHANNEL(CHANNEL01)           CHLTYPE(SVRCONN)
SSLCIPH(TLS_RSA_WITH_AES_256_CBC_SHA256)

If the channel does have an SSL cipher, and the application connecting to the channel has a different SSL ciper, the IBM MQ error log may contain something like this.

AMQ9631E: The CipherSpec negotiated during the SSL handshake does not match the
required CipherSpec for channel 'MANAGER01.CHANNEL01.SVR'.

In this scenario, the application or IBM MQ channel can be updated with the same SSL cipher. Or, for Java application, the SSL cipher class can be set to false.

-Dcom.ibm.mq.cfg.useIBMCipherMappings=false

Topic

If the user is attempting to publish/subscribe to a topic, use the display topic command to ensure that pub and sub are enabled.

PUB(ENABLED)           SUB(ENABLED)

Also use the dspmqauth command to ensure the user ID has the pub and sub permission to the Topic.

dspmqaut -m MANAGER01 -n TOPIC01 -t topic -p JohnDoe

Entity JohnDoe has the following authorizations for object TOPIC01: 
    pub
    sub

Queue

If the user is attempting to read, get or put a message on a queue, use the display queue command to ensure that get and put are enabled.

echo "display queue (QUEUE01) GET PUT " | runmqsc MANAGER01

Following is an example of what will be displayed.

QUEUE(queue01)             TYPE(QLOCAL)
GET(ENABLED)               PUT(ENABLED)
MAXDEPTH(5000)

Also use the dspmqauth command to ensure the user ID has the get, browse, put and inq permission to the Queue.

dspmqaut -m MANAGER01 -n QUEUE01 -t queue -p JohnDoe

Entity JohnDoe has the following authorizations for object QUEUE01: 
    get
    browse
    put
    inq