Work from connection setup to message receipt in order. Use a single synthetic topic and the quickstart before debugging a full application.
Broker setup and availability
Check the Broker overview and subscription state first. Pending checkout means payment setup is unfinished; provisioning means capacity is still being prepared. A past-due, canceled, suspended or failed state needs billing or operational attention before reconnecting devices. Follow the action shown in RunMQTT and the Broker state guide. That guide is not a live incident dashboard.
After a checkout return, allow time for the state to refresh. If the Broker remains pending or failed, contact support with its ID and the time of the attempt. Do not repeat checkout or create duplicate Brokers to recover an uncertain operation.
Diagnose by symptom
| Symptom | Check and next action |
|---|---|
| DNS failure or timeout | Copy the RunMQTT hostname again; test DNS and outbound access to 8883 for TLS or 443 for WSS. |
| Certificate failure | Use the hostname, not its IP; check the device clock and trusted CA store. Keep certificate verification enabled. |
| WSS handshake failure | Use the complete wss://…/mqtt URL; confirm the network proxy allows WebSocket upgrades. |
| Authentication rejected | Copy MQTT username and password from the same device and Broker. Do not use your account login, add signatures, or include surrounding whitespace. |
| Repeated connect/disconnect | Check for duplicate Client IDs first, then keepalive, network stability and Broker state. |
| SUBACK rejected | Check subscribe permission on the requested filter; a connection success does not grant every topic. For shared filters, check group syntax and negotiated capability. |
| Publish timeout or immediate disconnect | Check publish permission on the exact topic, chosen QoS, retain setting and message size. A rejected publish may not return a useful error. |
| Publish succeeds but nothing arrives | Confirm an active subscription on the same Broker, exact topic case and slashes, and recipient permissions. Wait for SUBACK and allow a few seconds before publishing again. |
| Old message appears at subscription | Check retained state and payload timestamp. Follow the retained cleanup in sessions and delivery. |
| Offline message is missing | Check stable Client ID, session expiry, sessionPresent, QoS and whether the subscription existed before disconnect. |
For TLS diagnostics without sending credentials:
openssl s_client -connect "$MQTT_HOST:8883" -servername "$MQTT_HOST" \
-verify_return_error </dev/null
Use MQTT_HOST from the quickstart. A successful TLS handshake proves only transport access; it does not verify MQTT authentication or topic permissions.
Policy changes and safe credential replacement
Policy changes can take time to reach live connections. After a change, allow several minutes, reconnect the test client, and repeat both an allowed and a denied operation. Check overlapping wildcard grants if a removed permission still appears to work. Do not treat a local policy preview as proof of live enforcement.
For an exposed or outdated password, open the device details or credentials side panel and choose Reset password. Confirm, copy the new password and update every client using this identity. Verify that the new password connects and the old one cannot establish a new connection. If you need to retire the identity entirely, delete the device. Do not rely on renaming a device or changing its Client ID to revoke access. Check existing connections separately when validating revocation.
Logs and usage
Open the Broker's Logs tab. Filter by available category, device, Client ID or error code and narrow the time of the failed operation. Record your timezone when comparing client timestamps. Missing log entries are not proof that a message was delivered; retain the client-side SUBACK, acknowledgement and receive results as well.
Use Usage to review connection and message trends over the available time ranges. Samples can lag current activity; this is not an instantaneous delivery counter. Dashboard test clients also consume connections and message deliveries. See plans and billing.
Plan allowances and technical boundaries
Plan allowances describe concurrent connections and monthly message units, not unlimited burst throughput or packet sizes. The RunMQTT policy form accepts filters up to 180 characters. Device names use 1–40 ASCII letters, digits, hyphens or underscores. Use short topic levels and small payloads initially, batch subscriptions conservatively, and bound reconnect traffic.
MQTT 5 clients should respect any advertised Maximum QoS, Maximum Packet Size, Receive Maximum, Retain Available and Shared Subscription Available values. Before deploying large payloads, high-rate publishing, many subscriptions or prolonged offline queues, validate the target Broker and contact RunMQTT with the required workload. Do not infer a per-second limit from a monthly allowance.
Ask for help
Send the Broker ID, approximate time and timezone, SDK/version, transport, MQTT version, sanitized topic/filter, QoS/retain settings and the smallest reproduction. Include whether connection, subscription, publication or receipt failed. Use the contact page; never send device passwords, private keys or sensitive payloads.