How to Test an MQTT Broker Connection
MQTT is a lightweight messaging protocol: devices publish messages to named channels called topics on a central server (the broker), and other clients subscribe to those topics. Testing an MQTT connection means proving, in order, that the broker is reachable, that authentication passes and that messages land on the right topic in the right format. This guide does it in six steps with an MQTT test client.
Five MQTT terms you need
| Term | Meaning |
|---|---|
| Broker | Server that receives messages and delivers them to subscribers (Mosquitto, EMQX, HiveMQ…) |
| Topic | The message’s address, e.g. site1/inverter3/power |
| Client ID | Unique identity of each connection |
| QoS | Delivery guarantee: 0 (at most once), 1 (at least once), 2 (exactly once) |
| Retained | The broker keeps the last message on a topic and sends it to new subscribers immediately |
Step 1: Port and network reachability
Default ports:
| Port | Use |
|---|---|
| 1883 | MQTT, unencrypted |
| 8883 | MQTT over TLS |
| 8083 / 8084 | WebSocket / secure WebSocket (varies by broker) |
If you can’t connect, first confirm the broker address and port are reachable from your network. Corporate networks and cellular modems often block 1883.
Step 2: Connect and read the CONNACK
The client sends CONNECT; the broker answers with CONNACK. MQTT 3.1.1 return codes:
| Code | Meaning | What to do |
|---|---|---|
| 0 | Accepted | Carry on |
| 1 | Unacceptable protocol version | Switch the client between 3.1.1 and 5.0 |
| 2 | Identifier rejected | Don’t use an empty or invalid client ID |
| 3 | Server unavailable | Check the broker service |
| 4 | Bad username or password | Verify credentials |
| 5 | Not authorized | The user isn’t allowed to connect |
Step 3: Watch for client ID collisions
When a second connection opens with the same client ID, the broker drops the first one. Copy a field device’s client ID into your test tool and both will disconnect each other in a loop. Always use a unique ID for testing (e.g. test-laptop-01).
Step 4: Subscribe wide first
If you don’t know which topic the data is on, start broad:
#→ every topic on the broker (if you’re allowed)site1/#→ everything undersite1site1/+/power→ thepowertopic of every inverter
Narrow the subscription once you see messages. On a busy or shared broker, # can return thousands of messages, so use it with care.
Step 5: Publish and read it back
Publish a test message (e.g. test/ping → hello) and confirm it arrives in a window subscribed to the same topic. This proves write (ACL) permissions work too.
Check the payload as well. If the device sends JSON, do the field names and number format match what the consuming software expects?
Step 6: Repeat over TLS
Production setups use 8883 and TLS. Common TLS failures:
- Certificate verify failed: the client doesn’t have the CA file that signed the broker’s certificate.
- Hostname mismatch: you connect by IP but the certificate was issued for a domain name.
- Client certificate required: the broker uses mutual TLS (mTLS).
Common failures
| Symptom | Likely cause |
|---|---|
| Connection timeout | Port closed, wrong address, firewall |
| Connects, drops after a few seconds | Client ID collision or keep-alive setting |
| Connected but no messages | Topic name differs (case, leading /) |
| Publish succeeds, subscriber gets nothing | No ACL permission, or a different QoS/retained expectation |
| Old value arrives | A retained message is still on the topic |
Public brokers for quick tests
Without your own broker, you can use test.mosquitto.org, broker.hivemq.com or broker.emqx.io. They are shared and public, so never send real site data or credentials.
Testing MQTT with Ranaliz iOT Tester
Ranaliz iOT Tester works as an MQTT test client: connect to a broker, subscribe, publish, with optional TLS. You can check whether a topic is right and whether the payload arrives without installing a separate MQTT Explorer.
What sets it apart is that the same app also tests Modbus and IEC 104. When a gateway reads Modbus and publishes over MQTT, you can verify both sides in one window: first read the Modbus register, then watch the same value land on the MQTT topic. It is free and runs on Windows and macOS.
FAQ
How do I check if MQTT is working?
Connect with an MQTT test client and confirm CONNACK code 0. Then subscribe to a topic and publish to the same topic. If the message comes back, the connection and permissions work.
What port does MQTT use?
1883 unencrypted, 8883 over TLS. WebSocket ports vary by broker.
Is there an MQTT Explorer alternative for Mac?
MQTTX and Ranaliz iOT Tester both run on macOS. MQTTX focuses on multiple connections and scripting. iOT Tester adds Modbus and IEC 104 testing in the same app.
Sources
- OASIS — MQTT Version 3.1.1 Specification
- OASIS — MQTT Version 5.0 Specification
