How do I troubleshoot Amazon MQ broker connection issues?

Short description

Amazon MQ broker connection issues can occur for many reasons and can result in many types of errors. The following are the most common reasons why Amazon MQ returns a connection-related error:

• Misconfigured local firewalls and routing tables
• Misconfigured security groups and network access control lists (NACLs)
• Connecting to the wrong port number
• DNS resolution issues
• Unsupported SDK clients
• Incorrect broker visibility settings
• Misconfigured SSL/TLS
• Out-of-date broker endpoint certificates

The following are examples of some of the error messages that Amazon MQ can return when there's a broker connection issue:

• SSLHandshakeException
• JMSException
• UnknownHostException
• SocketTimeoutException

Resolution

To troubleshoot Amazon MQ broker connection issues, do the following.

Verify that your local firewalls and routing tables are configured correctly

For brokers with public accessibility

Confirm the following:

• Your application has internet access.
• Your local firewalls and route tables allow public internet traffic.
• Your subnet NACLs and broker's security group allow communication through ports that are supported by Amazon MQ.
• The broker in your Amazon Virtual Private Cloud (Amazon VPC) is in a public subnet with a default route to an internet gateway. For more information, see Enable internet access in the Amazon VPC User Guide.

For private brokers

Confirm the following:

• AWS Cloud service-specific configurations associated with your Amazon MQ broker are set up correctly.
• Your local firewalls and route tables allow inbound and outbound traffic between any associated virtual private networks (VPNs).
• Your subnet NACLs and broker's security group allow communication through ports that are supported by Amazon MQ.

Test your Amazon MQ broker's network connectivity

Follow the instructions in step 5 of I can't connect to my broker web console or endpoints in the Amazon MQ Developer Guide.

Note: If the nslookup command request times out, or no values are present in the answer section of the command output, do the following:

• Clear your local DNS cache.
• Restart your local networking equipment and client.
• Verify that your local DNS servers are configured correctly.

Verify that you're using a supported SDK client

Make sure that you're using the most recent SDK client implementation that's compatible with the broker engine that you're using.

For Amazon MQ for ActiveMQ, you must use the AMQP 1.0 protocol. For Amazon MQ for RabbitMQ, you must use the AMPQ 0-9-1 protocol.

Make sure that you're using SSL/TLS to communicate with AWS resources

Note: Amazon MQ doesn't support Mutual Transport Layer Security (TLS) authentication currently.

The use of incorrect SSL/TLS versions and unsupported cipher suits results in SSL errors. For more information, see Data protection in Amazon MQ in the Amazon MQ Developer Guide.

For a list of supported ciphers for RabbitMQ and ActiveMQ, see Encryption in transit in the Amazon MQ Developer Guide.

Note: Some client libraries require SSL to be activated explicitly. The following are examples of explicit SSL activation for the Java and Ruby programing languages.

(Java) Explicit SSL activation code example

ConnectionFactory factory=new ConnectionFactory();
factory.useSslProtocol()

(Ruby) Explicit SSL activation code example

conn = Bunny.new(:tls => true, :verify_peer  => false)

Verify that you're Amazon MQ broker endpoint certificate is up to date

For more information, see the SSL exceptions section of the Amazon MQ Developer Guide.

For instructions on how to tell if the Amazon Trust Services Certificate Authorities (CAs) are in your trust store, see the following article: How to prepare for AWS's move to its own certificate authority.

---