How to Fix MQTT Broker Connection Issues

In this tutorial, you'll learn about How to Fix MQTT Broker Connection Issues. We cover key concepts, practical examples, and best practices.

The Problem

Your MQTT client cannot connect to the broker. The error log shows Connection refused: not authorized, Connection timed out, or No connection established. Without a broker connection, IoT devices cannot publish sensor data or receive commands.

Quick Fix

Fix 1: Broker Not Running

WRONG — assuming the Mosquitto broker is running:

mosquitto_pub -h localhost -t test -m "hello"
# Error: Connection refused

RIGHT — check broker status:

systemctl status mosquitto
# ● mosquitto.service - Mosquitto MQTT Broker
#    Loaded: loaded (/lib/systemd/system/mosquitto.service; enabled)
#    Active: inactive (dead)
sudo systemctl start mosquitto
mosquitto_pub -h localhost -t test -m "hello"
# (no output — published successfully)

For Docker:

docker run -d -p 1883:1883 --name mqtt eclipse-mosquitto
mosquitto_pub -h localhost -t test -m "hello"
# (no output — success)

Fix 2: Authentication Failed

WRONG — anonymous access without configuring credentials:

mosquitto_pub -h broker.example.com -t test -m "hello"
# Connection refused: not authorized

RIGHT — provide username and password:

mosquitto_pub -h broker.example.com -t test -m "hello" -u "sensor1" -P "mypassword"
# (no output — success)

Create credentials on the broker:

sudo mosquitto_passwd -c /etc/mosquitto/passwd sensor1
# Password: mypassword
sudo systemctl restart mosquitto

Fix 3: Firewall Blocking Port

WRONG — using the wrong port or firewall blocking:

mosquitto_pub -h broker.example.com -p 1883 -t test -m "hello"
# (connection timed out — port 1883 is blocked)

RIGHT — open the port or use an alternative:

# Check if the port is open:
nc -zv broker.example.com 1883
# nc: connect to broker.example.com port 1883 (tcp) failed: Connection timed out

# Open the port on the broker server:
sudo ufw allow 1883/tcp
# Or use port 8883 (MQTT over TLS) if 1883 is blocked
mosquitto_pub -h broker.example.com -p 8883 --cafile ca.crt -t test -m "hello"

Fix 4: WebSocket Port Mismatch

WRONG — using standard MQTT port for WebSocket connections:

# Browser client connects to ws://broker.example.com:1883
# (mosquitto on port 1883 does not accept WebSocket connections)

RIGHT — configure Mosquitto for WebSocket:

# /etc/mosquitto/conf.d/websocket.conf
listener 9001
protocol websockets

sudo systemctl restart mosquitto

Then connect to ws://broker.example.com:9001.

Fix 5: Client ID Conflict

# Another client is already connected with the same client ID
# Mosquitto disconnects the new client by default

RIGHT — use a unique client ID:

const char* clientId = "sensor1_kitchen";  // unique per device
client.connect(clientId, "sensor1", "password");
// or let the library generate a random ID:
client.connect(NULL, "sensor1", "password");

Fix 6: TLS Certificate Issues

mosquitto_pub -h broker.example.com -p 8883 -t test -m "hello" --cafile ca.crt
# Error: A TLS packet with unexpected length was received.

WRONG — connecting with TLS to a non-TLS broker:

# (the broker is not configured for TLS on port 8883)

RIGHT — verify TLS on the broker and use correct port:

# Broker config for TLS:
listener 8883
cafile /etc/mosquitto/ca.crt
certfile /etc/mosquitto/server.crt
keyfile /etc/mosquitto/server.key
require_certificate false

Use DodaTech's MQTT Inspector to test broker connectivity, view live messages, and diagnose authentication and TLS issues.

Prevention

• Enable Mosquitto to start automatically with sudo systemctl enable mosquitto.
• Configure authentication and authorization from the start.
• Open firewall ports for both MQTT (1883) and MQTTS (8883).
• Use unique client IDs per device.
• Test with a local broker before connecting to remote.

Common Mistakes with broker connection

1. Using return to exit a function early instead of wrapping a pure value in the monad
2. Mixing let bindings with <- bindings in do notation, producing type errors
3. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors

These mistakes appear frequently in real-world MQTT code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ