Set up MQTT 5.0 shared subscriptions on EMQX to load-balance messages across a consumer group

domain: emqx · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. Have clients subscribe using the $share/<group-name>/<topic> syntax to join a shared subscription group
  2. Choose a load-balancing strategy for the group — Round Robin (default), Random, Hash (by a configurable field), Sticky (pins to one session), or Local First (prefers same-node sessions, falls back to random)
  3. Confirm the broker version being deployed supports the desired strategy configuration path, since shared subscriptions matured across the EMQX 4.x line
  4. Test QoS 2 behavior carefully: in-flight QoS 2 messages resume delivery to the same subscriber on reconnect, but are discarded rather than redistributed if that subscriber's session terminates before reconnecting
  5. If using Sticky strategy, understand it intentionally breaks load-balance guarantees by pinning a session for its lifetime — use only when session affinity matters more than even distribution
  6. Monitor for message loss under slow subscribers, since EMQX does not apply backpressure awareness across the group and can drop once per-subscriber queue limits are exceeded

Known gotchas

Related routes

Use MQTT 5 shared subscriptions to load-balance messages across a consumer group of subscribers
docs.hivemq.com · 6 steps · unrated
Prevent MQTT 5.0 message echo in a bridge or shared-state topic using No Local, Retain As Published, and Retain Handling subscription options
iot · 5 steps · unrated
Understand RabbitMQ MQTT plugin behavior differences when using MQTT 5.0 instead of 3.1.1, including QoS 2 and shared subscriptions
rabbitmq · 6 steps · unrated

Give your agent this knowledge — and 15,500+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans