ActiveMQ "Connection refused" on port 61616 before broker ready in CI

The JMS client could not open the OpenWire transport on 61616 because the ActiveMQ broker has not finished starting. The broker boots its transports a few seconds after the container starts, so an early connect is refused.

What this error means

The client fails with "javax.jms.JMSException: Could not connect to broker URL: tcp://localhost:61616. Reason: java.net.ConnectException: Connection refused".

Terminal

javax.jms.JMSException: Could not connect to broker URL: tcp://localhost:61616.
Reason: java.net.ConnectException: Connection refused (Connection refused)

Common causes

The broker has not opened the OpenWire transport

The broker starts its transports after the container starts, so 61616 is not listening during the startup window.

The OpenWire port is not mapped

Only the web console (8161) is published, or the wrong port is used, so the JMS connection finds nothing on 61616.

How to fix it

Map 61616 and wait for the transport

Publish the OpenWire port and poll until it accepts a connection before tests.

Terminal

until nc -z localhost 61616; do echo "waiting for activemq"; sleep 3; done

Publish the broker port from the service

Map 61616 (and 8161 for the console) from the ActiveMQ service container.

.github/workflows/ci.yml

services:
  activemq:
    image: apache/activemq-classic:6.1.0
    ports: ['61616:61616', '8161:8161']

How to prevent it

Map the OpenWire 61616 port and connect on it.
Wait for the transport to accept connections before the first client.
Allow generous retries during broker startup.