RabbitMQ "Connection refused" before the broker is ready in CI

By Daniel Zoghalchali·Latchkey

The RabbitMQ container is starting, but the broker (an Erlang application) takes several seconds to boot and is not yet listening on 5672. AMQP clients get a refused connection. A rabbitmq-diagnostics healthcheck gates steps until it is ready.

What this error means

The first AMQP connection fails with "Connection refused - connect(2) for \"localhost\" port 5672" or "[Errno 111] Connection refused", then works once the broker has booted.

amqp.exceptions.AMQPConnectionError: [Errno 111] Connection refused
connect(2) for "localhost" port 5672

Common causes

The broker is still booting

RabbitMQ starts the Erlang runtime and the broker application before the AMQP listener is up, which takes several seconds on CI hardware.

No healthcheck waits for the broker to run

Without a rabbitmq-diagnostics health command, steps start as soon as the container exists, before the broker accepts connections.

How to fix it

Gate steps with a rabbitmq-diagnostics healthcheck

Hold steps until the broker reports running and the port is reachable.

services:
  rabbitmq:
    image: rabbitmq:3.13
    ports: ['5672:5672']
    options: >-
      --health-cmd "rabbitmq-diagnostics -q check_port_connectivity"
      --health-interval 10s
      --health-timeout 5s
      --health-retries 10

Poll the broker in a loop

For docker-compose, wait until the broker reports running.

until docker exec rabbitmq rabbitmq-diagnostics -q check_running; do
  echo "waiting for rabbitmq"; sleep 3
done

How to prevent it

• Add a rabbitmq-diagnostics healthcheck to the RabbitMQ service.
• Allow generous retries; the Erlang broker boot is not instant.
• Connect on the mapped localhost:5672 from steps.

Frequently asked questions

Related guides

References

• GitHub Actions documentation