Introduction

An ECONNREFUSED error against RabbitMQ in Docker Compose usually means your client tried to connect to the wrong address, the wrong port, or a broker that is not ready yet. The detail that trips people up most often is that 127.0.0.1 means different things depending on whether the code is running on the host machine or inside another container.

Understand the Address First

If your application is running on the host machine, 127.0.0.1:5672 means “connect to the RabbitMQ port published by Docker onto the host.” For that to work, your Compose file must publish the port:

1services:
2  rabbitmq:
3    image: rabbitmq:3-management
4    ports:
5      - "5672:5672"
6      - "15672:15672"

If your application is running inside another Compose service, 127.0.0.1 points back to that application container, not to RabbitMQ. In that case you should use the Compose service name as the host:

1services:
2  app:
3    build: .
4    depends_on:
5      - rabbitmq
6    environment:
7      RABBITMQ_HOST: rabbitmq
8      RABBITMQ_PORT: 5672
9
10  rabbitmq:
11    image: rabbitmq:3-management
12    ports:
13      - "5672:5672"
14      - "15672:15672"

Inside the Compose network, rabbitmq is the correct hostname.

Do Not Confuse Port 5672 with 15672

RabbitMQ uses different ports for different purposes:

• '5672 for AMQP client connections'
• '15672 for the management web UI'

A common mistake is seeing 15672 in the browser and then accidentally using it for the AMQP client connection. The management UI can be healthy while your application still fails if it tries the wrong port.

Check Whether the Broker Is Actually Running

Before changing application code, confirm that RabbitMQ started cleanly:

docker compose ps
docker compose logs rabbitmq

If the container is restarting, crashing, or still booting, the connection refusal is expected. A healthy container is necessary, but it still does not guarantee readiness for clients at the exact moment your app starts.

depends_on Does Not Mean Ready

In Compose, depends_on controls startup order, not application readiness. Your app may start before RabbitMQ finishes initializing.

A practical fix is to retry the connection in the app or add a health check:

1services:
2  rabbitmq:
3    image: rabbitmq:3-management
4    healthcheck:
5      test: ["CMD", "rabbitmq-diagnostics", "check_port_connectivity"]
6      interval: 10s
7      timeout: 5s
8      retries: 10

Then your application can wait for a healthy broker, or at least fail with a clearer startup sequence.

Verify Connectivity from the Right Place

If the app is containerized, test from inside that network rather than from the host:

docker compose exec app sh

From there, check whether the broker hostname resolves and the port is reachable. If DNS resolution works for rabbitmq but your code still uses 127.0.0.1, the bug is in configuration, not networking.

Example Client Configuration

A typical Node.js client should use environment variables instead of a hard-coded localhost address:

1const amqp = require("amqplib");
2
3const host = process.env.RABBITMQ_HOST || "localhost";
4const port = process.env.RABBITMQ_PORT || 5672;
5
6async function main() {
7  const connection = await amqp.connect(`amqp://${host}:${port}`);
8  const channel = await connection.createChannel();
9  await channel.assertQueue("jobs");
10  console.log("Connected");
11}
12
13main().catch(err => {
14  console.error(err.message);
15  process.exit(1);
16});

That makes it easy to use localhost on the host and rabbitmq inside Compose.

Common Pitfalls

The biggest pitfall is using 127.0.0.1 from inside a container. That does not refer to the RabbitMQ container unless RabbitMQ is running inside the same container, which is not the normal Compose setup.

Another common issue is mixing up ports 5672 and 15672. One is for clients, the other is for the web dashboard.

Teams also rely on depends_on and assume it guarantees readiness. It does not. Connection retries or health checks are still needed.

Finally, do not ignore the logs. RabbitMQ startup failures, bad credentials, or plugin problems often show up there immediately.

Summary

• 'ECONNREFUSED usually means wrong host, wrong port, or a broker that is not ready yet.'
• Use localhost only when the client runs on the host and the port is published.
• Use the Compose service name such as rabbitmq when the client runs in another container.
• Connect to port 5672 for AMQP and use 15672 only for the management UI.
• Check container logs and add retries or health checks so startup timing does not break the app.