Upgrade broker and clients to MQTT 5 support (e.g., EMQX, HiveMQ, Mosquitto 2.x); verify version negotiation succeeds in the CONNACK — if the broker downgrades to 3.1.1, MQTT 5 features will be silently unavailable
Use User Properties in PUBLISH packets to carry metadata (device type, firmware version, geographic region) as key-value pairs without embedding them in the payload; brokers forward user properties transparently to subscribers
Read Reason Codes on CONNACK, SUBACK, PUBACK, and DISCONNECT to get specific failure reasons (e.g., reason code 0x97 = Quota Exceeded, 0x87 = Not Authorized) instead of the opaque failure booleans of MQTT 3.1.1
Use Shared Subscriptions ($share/<group>/<topic>) to distribute messages across multiple consumer instances for horizontal scaling; the broker delivers each message to exactly one member of the share group in round-robin or random fashion
Set Message Expiry Interval on QoS 1/2 messages to discard stale commands; set Session Expiry Interval in CONNECT to control how long the broker retains session state after disconnect — use 0 for clean sessions or a nonzero value for persistent sessions
Use the Will Delay Interval in MQTT 5 LWT to defer publishing the will message; set it longer than the expected reconnection window so transient network glitches do not trigger false offline alerts
Known gotchas
Not all brokers claiming MQTT 5 support implement every feature; shared subscriptions and topic aliases in particular have inconsistent implementation — test explicitly on the target broker version
The Will Delay Interval is only honoured if the session persists (Session Expiry Interval > 0); with a clean session (expiry = 0) the will is published immediately on disconnect regardless of the delay setting
MQTT 5 prohibits retransmitting messages over a healthy TCP connection (unlike 3.1.1 which allowed it); client libraries built for 3.1.1 that retransmit without checking connection health will violate the spec and may be disconnected by strict brokers
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp