Why does my MQ resource adapter fail to start and report an MQJCA1008 error?
Paul_Titheridge |May 24 2017 Updated
Every once in a while, a customer will contact IBM Support and say:
I've got the MQ resource adapter deployed into an application server, and it fails to start with the error "MQJCA1008: An incorrect version of the MQ classes for JMS was found. Deployment failed". What's going on?
In this short blog post, I'll explain what the MQJCA1008 error message means and how to resolve it.
What's inside the MQ resource adapter
The MQ resource adapter is made up of a number of different components, as shown below:
Figure 1: The components that make up the MQ resource adapter.
The Java Message Queueing Interface (often referred to as the JMQI) is a Java implemention of the standard MQI, and handles all of the communication between the resource adapter and queue managers. The Local JMQI is used by applications that connect to a queue manager using the BINDINGS transport, and the Remote JMQI is used when an application connects to a queue manager using the CLIENT transport.
The MQ classes for JMS provide the MQ implementation of the JMS specification. The MQ classes for JMS have three modes of operation:
- MQ messaging provider normal mode
- MQ messaging provider normal mode with restrictions
- MQ messaging provider migration mode.
and are used by enterprise applications that perform outbound messaging, as well as activation specifications.
Speaking of activation specifications, the MQ resource adapter also contains a set of Connector classes. These classes provide an implementation of the Java Connector Architecture (JCA) specification which allow the application server to drive activation specifications in a standard way.
The final component in the resource adapter are the Headers and PCF classes. These classes allow enterprise applications to directly manipulate MQ headers on messages that they process, and perform administrative operations using Programmable Command Format (PCF) messages.
Why the MQJCA1008 error occurs and how to resolve it
As you can see, the MQ resource adapter contains a lot of stuff! This means that when it has been deployed into an application server, the resource adapter should have access to all of the classes that it requires to run. There is no need to:
- Copy the MQ relocatable JAR file, or install an MQ client, on to the same system as the application server.
- And configure the application server's CLASSPATH to load either the relocatable JAR file, or the MQ classes for JMS from the MQ Client installation directory.
Now, if:
- The MQ resource adapter has been installed into an application server.
- And the application server has been configured to load either the relocatable JAR file, the MQ classes for JMS from an MQ Client installation directory.
then it is possible that there will be two different versions of the MQ classes for JMS on the application server's CLASSPATH:
- One version provided by the MQ resource adapter.
- One version loaded from either the relocatable JAR file or the MQ Client installation directory.
This could potentially lead to unexpected behaviour, and exceptions such as ClassNotFoundException or NoSuchMethodError. In order to prevent this from happening, the MQ resource adapter contains logic to check that the version of the MQ classes for JMS on an application server's CLASSPATH match the version contained with the resource adapter itself. If the MQ resource adapter finds that the MQ classes for JMS are not the expected version, then a JMSException containing the message:
MQJCA1008: An incorrect version of the MQ classes for JMS was found. Deployment failed.
will be thrown and the resource adapter will fail to start.
So if the MQ resource adapter fails to start and reports the MQJCA1008 error, then you should check the application server's CLASSPATH and remove any entries for either the relocatable JAR file or the MQ classes for JMS. This will ensure that the resource adapter only picks up the MQ classes for JMS that are contained within it, and will work as expected.
As always, I hope this helps!