MQTT Troubleshooting Guide – The Business Resource Directory MQTT

MQTT Bridge Troubleshooting Guide (Starter, Pro, Business)

This guide covers the most common connection and data issues across all MQTT tiers, plus a few tier-specific checks. If you’re using Mesh-Plug (WordPress) or Meshtastic, the “Mesh-Plug and Meshtastic” sections will save you time.

Quick start; what you need to know

Most issues come down to one of these:

Wrong port (TLS vs WebSocket)
Wrong hostname (broker vs API endpoint)
Missing/incorrect username + password
Wrong topic root or duplicated root (example: msh/msh/...)
Client doesn’t trust the CA certificate (TLS)
You’re connected, but publishing/subscribing to topics your account can’t access (ACL/permissions)

1) Identify your tier and connection type

Connection types (most common)

A) MQTT over TLS (recommended for devices/servers)

Port: 8883
Used by: ESP32/ESP8266, Mosquitto CLI, Node apps, backend services

B) MQTT over WebSocket (recommended for browsers/WordPress dashboards)

Port: 9001 (commonly)
Used by: Mesh-Plug and browser-based dashboards

If your app is a web page (JavaScript in the browser), it must use WebSocket; browsers cannot speak raw MQTT/TLS directly.

2) “Is the service up?” checks (all tiers)

A. Basic network sanity

From a machine on the same network as your client:

Confirm DNS resolves:
- ping <broker-hostname> (or nslookup <broker-hostname>)
Confirm ports are reachable:
- If you have nc:
  - nc -vz <broker-hostname> 8883
  - nc -vz <broker-hostname> 9001

If ports are blocked, check:

Local firewall
Router outbound rules
Corporate network restrictions (often blocks 8883)

B. WebSocket reverse proxy sanity (for WordPress / browser)

If you use Nginx in front of MQTT WS:

A “connected but no data” symptom can be a proxy config issue
A 502 Bad Gateway usually means:
- Nginx can’t reach the upstream WebSocket listener; wrong upstream host/port; service down

3) Credentials and ACL issues (all tiers)

Symptoms

Connect fails immediately
Or connects, but publishes/subscribes silently fail
Logs show “Not authorized” or “ACL denied”

Fix

Verify you are using the exact username/password issued for that bridge
Confirm you did not include extra spaces when copying credentials
Confirm your client is subscribing/publishing to the allowed topic namespace for that bridge

Tip: ACL problems often look like “nothing happens” because some clients don’t surface the rejection clearly.

4) TLS problems (Starter/Pro/Business)

Common TLS symptoms

“certificate verify failed”
“unknown CA”
“handshake failure”
Works on one machine but not another

Fix checklist

Confirm you’re on the TLS port (8883)
Use the system CA bundle where possible
If your client needs a CA file, use your OS CA store or the CA bundle path provided by your platform

Mosquitto CLI test (TLS):

mosquitto_pub -d \
  -h <broker-hostname> -p 8883 \
  --cafile /etc/ssl/certs/ca-certificates.crt \
  -u "<username>" -P "<password>" \
  -t "<allowed-topic>/hello" \
  -m "auth ok"

If this works, your credentials and TLS path are good; the problem is likely your original client config (topic root, WS vs TLS, or ACL namespace).

5) WebSocket problems (WordPress / Mesh-Plug)

Common WS symptoms

Dashboard shows “Connected” but no nodes/data
White map; empty tables; headers visible
JavaScript console errors
Data appears only sometimes (intermittent)

Fix checklist

Confirm you’re using the WebSocket port (often 9001)
Confirm the URL is wss://... (secure websocket) when your site is HTTPS
Confirm your reverse proxy supports WebSocket upgrade headers
Confirm your WordPress site is not blocking the websocket due to mixed content or CSP rules

Browser console check
Open DevTools → Console:

Look for WebSocket connection to ... failed
Look for 401/403 style errors (auth/ACL)
Look for JSON parse errors (bad payload format)

6) Topic root problems (very common; all tiers)

The classic symptom

You are connected, but you see no messages; or you see messages in one place but not another.

What’s happening

Your publisher and subscriber are using different topic roots, or you accidentally duplicated the root.

Example of a duplication:

Expected: msh/2/json/...
Actual: msh/msh/2/json/...

Fix

Decide your single canonical root (example: msh)
Make sure:
- Meshtastic MQTT settings use msh once
- Mesh-Plug “Root topic” uses msh once
- Any bridge prefixes (if you use them) are consistent everywhere

Quick debug
Subscribe broad (temporarily) to see what’s actually arriving:

mosquitto_sub -d -h <broker-hostname> -p 8883 \
  --cafile /etc/ssl/certs/ca-certificates.crt \
  -u "<username>" -P "<password>" \
  -t "#"

Then refine back down after you confirm the real topic structure.

7) Mesh-Plug and Meshtastic specific troubleshooting

A) “Nodes list empty” but you see traffic elsewhere

Confirm Mesh-Plug’s subscription topics include position and/or telemetry types your mesh is actually publishing
Confirm your Meshtastic device is configured to send:
- Position updates
- Telemetry (if you expect sensor readings)

B) “Chat not showing”

Chat visibility often depends on:

Correct topics for Meshtastic text payloads
Correct channel mapping
Whether your node is actually forwarding chat to MQTT (some setups forward only certain message types)

C) Map marker jumps/drifts

This is usually not “drift”; it’s one of:

Node reporting stale coordinates
Position derived from last known fix; poor GPS lock
Mixed node identity; you’re seeing a relayed node’s last fix
Time/clock skew causing the “latest” position logic to pick the wrong record

Fix checklist

Ensure the node has a GPS module and reliable satellite lock
Ensure the node is configured to publish position periodically
Confirm Mesh-Plug uses message timestamps consistently (device time vs broker receive time)

D) macOS Meshtastic app quirk (important)

In some macOS client setups, the Meshtastic app may not emit NodeInfo packets over MQTT reliably. If Mesh-Plug depends on NodeInfo for names/metadata, you can see “ID but no name” behavior.

Workaround

In Mesh-Plug settings, manually set the Gateway Hex (if your setup uses it) so identification and association work even when NodeInfo packets are missing.

8) Tier-specific troubleshooting

Starter tier (typical issues)

Starter plans usually have simpler limits; common pain points:

Hitting connection/session limits (too many reconnecting clients)
Using a browser dashboard plus a device plus a phone; exceeds expected concurrency
Publishing outside allowed namespace

If you suspect limits

Disconnect all but one client
Test with Mosquitto CLI publish/subscribe
Then add clients back one at a time

Pro tier (typical issues)

Pro often adds features like multiple clients, expanded ACL, or more throughput.
Common pain points:

Multiple topic namespaces; one client publishes to the wrong namespace
Retained messages or “last will” behavior confusing dashboards

Fix

Standardize a single topic convention per deployment
Clear retained messages if you’re seeing “ghost” data:
- Publish empty retained payload to the retained topic (implementation varies)

Business tier (typical issues)

Business setups commonly involve:

Multiple bridges/environments (staging vs production)
Multiple sites consuming the same broker
Webhook/automation integrations

Common pain points:

Using staging credentials against production broker (or vice versa)
Integrations expecting QoS/retained behavior that isn’t configured consistently
De-provisioning events on cancel/suspend not reflected immediately in client apps (they keep retrying with old creds)

Fix

Label credentials clearly (ENV + Bridge ID)
Rotate credentials if there’s any doubt which set is active
After cancellation/suspension, remove creds from devices; reboot device to stop reconnect storms

9) Common error messages and what they mean

“Connection refused”
- Wrong host/port; service down; firewall block
“Not authorized” / “ACL denied”
- Wrong username/password; topic not permitted
“certificate verify failed”
- CA trust issue; incorrect TLS settings; MITM proxy on network
Browser shows “WebSocket closed”
- Wrong WS URL; proxy doesn’t support upgrade; auth rejected; mixed content