🐰 RabbitMQ Error: MQTT plugin connection refused / not enabled

Exact Error Message

An MQTT client connecting to a broker where the plugin is not enabled (or the port is closed) fails with a refused TCP connection:

mqtt.connect: Error: connect ECONNREFUSED 10.0.4.21:1883

When the plugin is enabled but authentication fails, the broker instead returns an MQTT CONNACK with a non-zero return code, and the log shows:

2026-07-17 12:05:33.812 [warning] <0.1533.0> MQTT connection from 10.0.7.44:44112 rejected:
 CONNACK 'not_authorized' (rc=5) for client-id 'sensor-17' user 'anonymous'

A bad username/password surfaces on the client as:

Connection refused: Bad username or password (CONNACK return code 4)

What It Means

RabbitMQ speaks MQTT through the rabbitmq_mqtt plugin, which must be enabled before any MQTT client can connect. MQTT listens on its own ports — 1883 for plaintext and 8883 for TLS — which are separate from the AMQP port 5672 and the management port 15672. A ECONNREFUSED almost always means the plugin is not enabled, the port is not being served, or a firewall/security group is blocking it.

If the TCP connection succeeds but the client is rejected, the failure moves into the MQTT protocol itself: the broker returns a CONNACK return code. Code 4 is bad username/password, code 5 is not authorized (permissions/vhost). By default MQTT connections map to a configured vhost and can use a default (guest-style) user, so credential and vhost-mapping mistakes are the most common post-enable failure.

Common Causes

• The rabbitmq_mqtt plugin is not enabled.
• Port 1883/8883 is blocked by a firewall or security group, or the listener is bound to the wrong interface.
• Wrong username/password, or the client sends none while anonymous login is disabled.
• The MQTT vhost mapping points to a vhost the user has no permissions on.
• TLS client using 8883 while the broker has no MQTT TLS listener configured.
• Duplicate client-id causing the broker to close the older session.

Diagnostic Commands

Confirm the plugin is enabled:

rabbitmq-plugins list -e | grep mqtt

Confirm the MQTT listener is actually bound and on which port:

rabbitmq-diagnostics listeners | grep -i mqtt
rabbitmq-diagnostics check_port_connectivity

Verify the user and its permissions on the mapped vhost:

rabbitmqctl authenticate_user sensor-svc 'REDACTED'
rabbitmqctl list_permissions --vhost /

Watch the log during a connect attempt for CONNACK rejections:

journalctl -u rabbitmq-server --since "5 min ago" | grep -iE 'mqtt|connack|not_authorized|bad username'

Step-by-Step Resolution

1. Enable the plugin if it is missing, then retry the client:

   rabbitmq-plugins enable rabbitmq_mqtt

2. Confirm the listener is up on 1883 (and 8883 for TLS):

   rabbitmq-diagnostics listeners | grep -i mqtt

3. Open the port in the host firewall / cloud security group if the connection is still refused from the client’s network. From the client host:

   nc -zv 10.0.4.21 1883

4. Fix authentication. For CONNACK code 4, correct the username/password; verify them against the broker:

   rabbitmqctl authenticate_user sensor-svc 'the-password'

5. Fix authorization / vhost mapping (CONNACK code 5). Grant the user permissions on the vhost MQTT maps to, and confirm the mqtt.vhost / default-user settings in rabbitmq.conf:

   rabbitmqctl set_permissions -p / sensor-svc ".*" ".*" ".*"

6. Decide on anonymous logins. If clients connect without credentials, either supply a username/password in the client or configure an explicit default MQTT user in rabbitmq.conf (mqtt.default_user / mqtt.default_pass) rather than relying on guest, which is restricted to localhost.

7. Verify the client connects and appears as an MQTT connection:

   rabbitmqctl list_connections name protocol user state | grep -i mqtt

Prevention

• Enable rabbitmq_mqtt as part of provisioning so the port is always served after a rebuild.
• Manage firewall/security-group rules for 1883/8883 alongside the broker deployment.
• Give each device a unique client-id and dedicated credentials; avoid the localhost-only guest user.
• Explicitly set the MQTT vhost and default user in rabbitmq.conf and grant matching permissions.
• Monitor CONNACK rejection rates and connection churn. The prompt library has prompts for building IoT/MQTT onboarding and auth-troubleshooting runbooks.

Related Errors

• Web-MQTT WebSocket failed — the browser variant over rabbitmq_web_mqtt, a different listener.
• access_refused (403) — the AMQP-side equivalent of a not-authorized CONNACK.
• connection refused — nothing listening on the port, the same root cause as an unenabled plugin.
• STOMP CONNECT error — the analogous auth failure on the STOMP plugin.

Frequently Asked Questions

Why is my MQTT connection refused before any auth happens? ECONNREFUSED means no listener answered — usually the rabbitmq_mqtt plugin is not enabled or port 1883 is blocked by a firewall.

Which port does RabbitMQ MQTT use? 1883 for plaintext and 8883 for TLS. These are separate from AMQP’s 5672 and management’s 15672.

What does CONNACK return code 4 vs 5 mean? Code 4 is bad username or password; code 5 is not authorized, typically a permissions or vhost-mapping problem.

Why can’t I connect with guest over MQTT? The guest user is restricted to localhost by default. Configure a dedicated MQTT user with mqtt.default_user/default_pass or send real credentials.

How do MQTT topics map to RabbitMQ? The plugin routes MQTT topics through the amq.topic exchange using dot-separated routing keys, so topology and permissions on that vhost matter. For more, see the RabbitMQ guides.