Troubleshoot JMS Integration

This topic covers troubleshooting issues related to integrating a JMS-compliant message broker with Kaazing Gateway.

For information on troubleshooting JMS clients, see Troubleshoot Your Clients.

For general troubleshooting information, see Troubleshoot Kaazing Gateway.

What Problem Are You Having?

Exception: “Name Not Found” When Using TIBCO EMS

Cause: When you try to run a client application against TIBCO EMS 5.x, you get an exception that looks similar to the following:


The TIBCO_HOME/ems/5.1/bin/factories.conf file may not be correctly configured.

Solution: To prevent this error, ensure that the TIBCO_HOME/ems/5.1/bin/factories.conf file is correctly configured according to the TIBCO EMS 5.x documentation. You can alternatively copy the contents of the file from the TIBCO EMS 5.x samples (TIBCO_HOME/ems/5.1/samples/config) into the factories.conf file.

Exception: “No Initial Context Exception” When Using TIBCO EMS

Cause: When you try to start the Gateway, you get an exception that looks similar to the following:


This error may occur if you do not have the necessary TIBCO EMS JAR files in your GATEWAY_HOME.

Solution: To prevent this error, copy the following client JAR files from TIBCO_HOME/ems/version/lib to GATEWAY_HOME/lib:

Then, restart the Gateway.

Exception: Service Unavailable When Using TIBCO EMS

Cause: After starting the Gateway, you see the following error:


This error may occur if you have not started TIBCO EMS before starting the Gateway.

Solution: To resolve this error, start TIBCO EMS, then restart the Gateway.

Connection Errors

Cause: There are two typical scenarios specific to JMS integration with the Gateway:

  1. The Gateway goes offline when a message sent by a JMS client is in transit. The result is that the message is lost and consumers do not get the message even after the Gateway comes back online. (If messages are sent after the Gateway is offline, the Kaazing Gateway JMS client accumulates the messages as pending frames and when the Gateway comes back online, the pending messages are sent.)
  2. The JMS-compliant message broker goes offline and the JMS client sends a message. The result is that messages are queued by the Gateway until the broker comes back online, at which point the messages are sent to the broker and on to subscribers (topics or queues).

Solution: From the JMS client side, the Kaazing Gateway Client APIs have several exception classes that can be used to determine what condition resulted in a connection error. For example, see the Java JMS Client API. A few of the key exception classes are:

For administrators of the Gateway, examining the error log (GATEWAY_HOME/log/error.log) of the Gateway indicates whether the Gateway can connect to the broker. For example, if the broker is offline, a record such as the following will appear in the error log:

2012-09-20 14:48:32,998 WARN Unable to establish JMS Connection due to the following exception: Could not connect to broker URL: tcp://localhost:61616. Reason: Connection refused


Exception: A synchronous method call is not permitted

Cause: When your client attempts to establish more than one distinct topic subscription (meaning either different topics or different message selectors) or if there is more than one queue consumer, you receive the following error message:

A synchronous method call is not permitted when a session is being used asynchronously: 'createConsumer'. The JMS specification does not permit the use of a session for synchronous methods when asynchronous message delivery is running.

Your JMS-compliant message broker strictly enforces the session threading rules of the JMS 1.1 specification, section 2.8 Multithreading. Specifically, the Session object does not support concurrent use in JMS 1.1. Session objects may be accessed by one logical thread of control at a time, only. The restriction makes JMS easier to use for some clients.

Solution: Add <workaround>1</workaround> to the jms service configured on the Gateway. For example:



    <!-- The location of the .bindings file -->


An Authentication Error Occurs when Trying to Connect the Gateway to the Message Broker

Cause: Authentication errors can occur if the authentication settings on the message broker are changed and the configuration of the Gateway has not been updated.

Solutions: The following options are available:

Note: When connecting the Gateway to some message brokers, you might need to set the username and password attributes of ConnectionFactory in the .bindings file in addition to the above solutions.

Exception: ClassNotFoundException

Cause: A required jar file is missing from the GATEWAY_HOME/lib/ext folder.

Solution: Review the procedure for integrating Kaazing Gateway with the message broker and ensure that all of the required jar files listed in the procedure are in the GATEWAY_HOME/lib/ext folder. To locate the procedure, see About Integrating Kaazing Gateway and JMS-Compliant Message Brokers.

TIBCO EMS Unable to Free Up Durable Subscribers

Cause: TIBCO EMS is unable to detect connection loss and free up durable subscribers when a Gateway instance shuts down unexpectedly.

Solution: To avoid this failure, the following two settings should be put in the TIBCO EMS server configuration file (tibemsd.conf):

Warning: maximum.pending.acknowledgments has been set to 1

Cause: The JMS service property maximum.pending.acknowledgments has been set to 1 because the JMS provider does not support individual message acknowledgment. Client applications must acknowledge each message received on a durable subscriber or queue in order to receive further messages on that subscriber or queue. Otherwise, the client will receive only one message from that queue or durable subscriber.

Solution: If you are using a JMS provider other than Apache ActiveMQ or TIBCO Enterprise Message Service (TIBCO EMS), you must ensure your client applications acknowledge each message received from a queue or durable subscriber.

See Also

For more information about Kaazing Gateway administration, see the documentation.