Overview
This guide covers the most common MQTT failures in gateway and broker integrations: TLS certificate problems, topic mismatches, DNS issues, authentication confusion, and broker reachability problems. Use it with the MQTT guide when publishing BACnet or Modbus data to brokers and cloud platforms.
Diagnostic Flow
- Confirm the broker hostname, port, and transport mode.
- Confirm the authentication method expected by the broker.
- Verify TLS certificate format and certificate chain.
- Publish and subscribe to a minimal test topic.
- Confirm the production topic structure and payload expectation.
Project Startup Questions
Before an MQTT job is treated like routine commissioning, answer these questions:
- Which broker or cloud platform is the target?
- Is TLS required, and are the certificates in the right format?
- What auth mode is the broker expecting?
- What exact topic hierarchy and payload contract should the gateway publish?
Symptoms & Solutions
| Symptom | Likely Cause | Action | Related Page |
|---|---|---|---|
| TLS handshake fails | Wrong certificate format or incomplete CA chain | Convert to PEM where required and reload the full chain | MQTT |
| Connects then disconnects repeatedly | DNS resolution or broker identity issue | Verify hostname resolution and broker certificate identity | MQTT |
| Messages publish but downstream system ignores them | Topic hierarchy or payload mismatch | Confirm topic structure and consumer expectations | MQTT |
| Authentication rejected | Wrong auth mode selected | Verify credentials versus certificates versus tokens | MQTT |
| Gateway enters unstable state under large publish loads | Job exceeds practical device or firmware limits | Reduce publish volume and validate point and job count | QuickServer |
Configuration Issues
Check TLS Artifacts First
If a secure MQTT connection fails, inspect certificate format, CA chain, and broker hostname before changing application settings. Many MQTT issues that look like protocol bugs are certificate preparation problems.
Treat Broker Identity As Intake, Not Cleanup
If the hostname, port, auth mode, or cloud platform still changes during commissioning, the project is not yet stable enough for meaningful troubleshooting.
Validate a Minimal Topic
Before publishing the full production set, publish one small known-good topic and confirm it appears correctly in an independent MQTT client. This separates broker connectivity from mapping or payload issues.
Watch for Capacity Assumptions
Large publish jobs, high point counts, or overly aggressive task layouts can destabilize gateway projects. If the system only fails at scale, test a reduced configuration before assuming the broker is the problem.
Tools
| Tool | Type | Description |
|---|---|---|
| MQTT Explorer | Client | Topic browser and live message inspection |
| Mosquitto | Broker and CLI | Broker plus publish and subscribe CLI testing |
| MQTTX | Client | Cross-platform test client for broker validation |
Need Help?
Before escalating an MQTT issue, capture the broker hostname, port, auth mode, certificate format, a minimal working or failing topic, and any disconnect or DNS error text. That usually cuts the problem space down to connectivity, TLS, or topic design.