🚨 RabbitMQ Error Guide: 'Failed to start Ranch listener' Management Plugin on 15672

Exact Error Message

When the management plugin cannot bind its HTTP listener, the broker log records a failed Ranch listener and a supervisor crash:

2026-06-29 09:14:02.771 [error] <0.612.0> Failed to start Ranch listener rabbit_web_dispatch_sup_15672
in ranch_tcp:listen([{cacerts,...},{port,15672}]) for reason eaddrinuse (address already in use)

2026-06-29 09:14:02.773 [error] <0.611.0> CRASH REPORT Process <0.611.0> with 0 neighbours exited
with reason: {could_not_start_listener,[{port,15672}],eaddrinuse}
in application_master:init/4 line 138

2026-06-29 09:14:02.780 [error] <0.43.0> Error description:
{could_not_start,rabbitmq_management,{bad_return,{...,{shutdown,...}}}}

If the plugin is simply not enabled, there is no error at all — the UI just refuses connections:

curl: (7) Failed to connect to localhost port 15672: Connection refused

What the Error Means

The management plugin serves its UI and HTTP API through a Cowboy/Ranch TCP listener bound to port 15672 (or 15671 for TLS). At boot, rabbitmq_management asks Ranch to open that socket. If the bind fails — most often because the port is already taken (eaddrinuse) or the listener config is malformed — Ranch returns an error, the plugin’s supervisor cannot complete startup, and the broker reports could_not_start_listener.

A Connection refused with no log error is a different failure: the plugin was never enabled, so nothing ever tried to bind 15672. Both end with “the UI is unreachable,” but the fix is opposite — one is a binding conflict, the other a missing plugin.

Common Causes

• Port already in use (eaddrinuse). Another process — a stale beam.smp, a second broker, an exporter, or a proxy — already holds 15672.
• Plugin not enabled. rabbitmq_management is absent from the enabled plugins, so the listener is never created.
• A previous broker instance did not release the socket. A crash or kill -9 left the port in TIME_WAIT or held by a zombie BEAM.
• Bad listener configuration. A malformed management.tcp.port / management.listener block, or a bind IP that does not exist on the host.
• TLS misconfiguration on 15671. Missing or unreadable certificate files make the secure listener fail to start.
• Insufficient privilege to bind. Binding a low/reserved port or a restricted IP without the right capabilities.

How to Reproduce the Error

Occupy 15672 before starting the broker, then watch the listener fail:

# hold the port with a throwaway process
python3 -m http.server 15672 &

# start (or restart) RabbitMQ; the management listener now collides
systemctl restart rabbitmq-server
# log shows: Failed to start Ranch listener ... reason eaddrinuse

To reproduce the “not enabled” variant, disable the plugin and curl the port:

rabbitmq-plugins disable rabbitmq_management
curl -i http://localhost:15672/   # Connection refused — no listener exists

Diagnostic Commands

# Is the management plugin enabled and running?
rabbitmq-plugins list -e | grep -i management

# What is actually holding port 15672?
sudo ss -ltnp | grep ':15672'

LISTEN 0  128  *:15672  *:*  users:(("python3",pid=9182,fd=3))

# Ask the broker which listeners it believes are up
rabbitmq-diagnostics listeners

Interface: [::], port: 5672, protocol: amqp, purpose: AMQP 0-9-1 and AMQP 1.0
Interface: [::], port: 15672, protocol: http, purpose: HTTP API   <-- absent when the listener failed

# Pull the listener startup errors out of the log
sudo grep -iE 'Ranch listener|could_not_start_listener|eaddrinuse' \
  /var/log/rabbitmq/rabbit@$(hostname -s).log | tail -10

# Confirm the configured management port and bind address
rabbitmq-diagnostics environment | grep -iA3 'management'

If ss shows a non-RabbitMQ process on 15672, you have a conflict. If rabbitmq-plugins list -e shows no management line, the plugin is simply disabled.

Step-by-Step Resolution

1. Decide which failure you have. A log line containing Failed to start Ranch listener ... eaddrinuse means a port conflict. A clean Connection refused with the plugin missing from list -e means it is not enabled.

2. Enable the plugin if it is missing:

   rabbitmq-plugins enable rabbitmq_management

   This persists across restarts and starts the listener immediately on a running node.

3. For eaddrinuse, identify and clear the squatter. Use ss -ltnp to find the PID on 15672. If it is a stale beam.smp from a crashed broker, stop the service cleanly and confirm the port frees; if it is an unrelated service, stop it or move RabbitMQ to a different management port.

4. Move the management port if the conflict is permanent. In rabbitmq.conf:

   management.tcp.port = 15673

   Then restart and update any proxy/monitoring that targeted 15672.

5. For a stuck socket after a hard kill, ensure no orphan BEAM remains, then restart. The port should be free once the old process is gone.

6. For TLS listener failures on 15671, verify the certificate and key paths in management.ssl.* exist and are readable by the rabbitmq user, then restart.

7. Verify recovery:

   rabbitmq-diagnostics listeners | grep 15672
   curl -s -o /dev/null -w '%{http_code}\n' http://localhost:15672/

   A 200/401 (not Connection refused) confirms the listener is up.

Prevention and Best Practices

• Reserve 15672/15671 exclusively for RabbitMQ on broker hosts; document the port so no exporter or proxy claims it.
• Enable rabbitmq_management through configuration management so a rebuilt node always comes up with the UI, not as a manual afterthought.
• Always stop the broker with systemctl stop / rabbitmqctl stop, never kill -9, so the listener socket is released cleanly.
• Keep TLS certificate paths and permissions under the same automation that renews them, so 15671 never fails on a missing file.
• Add a health check that curls 15672 after every restart and alerts on Connection refused, so a failed listener is caught before users notice.
• When changing the management port, update proxies, dashboards, and monitoring in the same change.

Related Errors

• HTTP access denied / 401 / 403 — the listener is up but rejects your credentials or tag; a different, post-bind failure.
• statistics database could not be contacted — the UI loads but metrics pages error.
• epmd … nxdomain / address already in use on 4369 — a related “port already taken” failure, but for the Erlang port mapper rather than the HTTP listener.
• could_not_start (other plugins) — the same supervisor pattern when a different plugin fails to initialise.

See more in the RabbitMQ troubleshooting series.

Frequently Asked Questions

Why is 15672 refusing connections with nothing in the log? The plugin is almost certainly not enabled, so no listener was created. Run rabbitmq-plugins enable rabbitmq_management.

What does eaddrinuse mean here? Another process already bound the port RabbitMQ wants. Use ss -ltnp to find it, then free the port or change management.tcp.port.

Can I run the management UI on a different port? Yes. Set management.tcp.port in rabbitmq.conf, restart, and repoint anything that used 15672.

Will a failed management listener stop AMQP from working? No. AMQP on 5672 starts independently; you can still publish and consume while the UI is down, which is why the failure is easy to miss.

Why did the port stay busy after RabbitMQ crashed? A kill -9 can leave an orphaned beam.smp holding the socket. Confirm no stale BEAM remains before restarting.