MQRC 2540: Channel name unknown

What it means

A client connection names a server-connection channel. The client sends that name to the queue manager when it connects, and the queue manager looks for a channel definition to match. If there isn't one, the connect fails with MQCC_FAILED and reason 2540. IBM's only advice is to make sure the client uses the right channel name.

Channel names are case-sensitive, and MQSC folds unquoted names to uppercase. A channel defined with DEFINE CHANNEL(app.svrconn) is really APP.SVRCONN, so a client asking for app.svrconn won't find it. The name comes from different places depending on how the client is set up. It may be in the MQSERVER environment variable, in the format CHANNEL/TCP/host(port), in a client channel definition table (CCDT), in a JMS connection factory, or in the MQCD passed on MQCONNX.

The network connection worked, so a listener is running at the host and port. That listener may belong to a different queue manager from the one where the channel was defined, which is a common source of confusion on hosts that run several queue managers.

Common causes

• A typo or wrong case in the channel name in MQSERVER, the CCDT, the connection factory or the application's code.
• The server-connection channel was never defined on this queue manager, or was deleted.
• The client reaches a listener belonging to a different queue manager on the same host, where that channel doesn't exist.
• The CCDT has a CLNTCONN entry whose name doesn't match any SVRCONN on the server. The two names must be the same.

How to find the problem

1. Check the server for the channel with DISPLAY CHANNEL(APP.SVRCONN) CHLTYPE in runmqsc. On z/OS, use the same command with the command prefix.
2. Read the queue manager error log. It records the name the client asked for, so you can compare it character by character.
3. Check where the client gets its channel name. Look at echo $MQSERVER, the CCDT location (MQCHLLIB and MQCHLTAB, or the ChannelDefinitionDirectory in mqclient.ini), or the connection factory.
4. Confirm which queue manager owns the listener on that port, with DISPLAY LSSTATUS(*) PORT on each queue manager.

How to fix it

• Correct the channel name in the client configuration, matching case exactly.
• Define the server-connection channel on the right queue manager, for example DEFINE CHANNEL(APP.SVRCONN) CHLTYPE(SVRCONN) TRPTYPE(TCP), and add CHLAUTH rules for it.
• Make CLNTCONN names in the CCDT identical to the SVRCONN names on the server.
• Point the client at the port of the queue manager that owns the channel.

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 '2540' ('MQRC_UNKNOWN_CHANNEL_NAME').

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.