Direct answer

Adopt MQTT 5 when its operational semantics remove real application work: precise reason codes, independent session expiry, message expiry, request/response metadata, subscription identifiers, or negotiated receive limits. MQTT 3.1.1 remains a sound choice for a stable installed base when those capabilities do not change an operational decision. Treat adoption as a compatibility migration, not a flag-day version upgrade.

Scope and non-scope

This comparison covers protocol behavior that affects device fleets and broker operations. It does not compare vendor clustering, storage engines, dashboards, or proprietary extensions. A broker advertising MQTT 5 support may serve both versions while exposing different limits by listener or SDK, so support claims do not replace interoperability tests.

MQTT 5 retains the publish/subscribe model and QoS levels from 3.1.1. Its main addition is structured control data. CONNECT, CONNACK, PUBLISH, acknowledgements, SUBACK, and DISCONNECT can carry properties or more precise reason codes. That makes failures diagnosable and policies expressible, but it also increases packet size, parser surface, and state on constrained clients.

Decide from capabilities

Choose a feature with a defined owner and outcome. Message Expiry Interval prevents commands or transient telemetry from living indefinitely in an offline queue. Session Expiry Interval separates “start without previous state” from “how long should this state survive,” replacing the overloaded 3.1.1 clean-session behavior. Receive Maximum and Maximum Packet Size let a client state inbound limits instead of relying only on configuration outside the protocol.

Topic aliases reduce repeated topic bytes on a stable connection, but both peers must manage connection-scoped alias state correctly. Response Topic and Correlation Data standardize request/response metadata; they do not turn MQTT into synchronous RPC or guarantee that a responder is available. Subscription Identifiers can attribute a delivery to matching subscriptions. Server Keep Alive, Assigned Client Identifier, and Server Reference improve centrally managed connection behavior when the client handles them deliberately.

Stay on 3.1.1 when the client footprint is severely constrained, the deployed fleet cannot be updated safely, or platform conventions already solve the relevant problem without ambiguity. Verify the exact broker, SDK, gateway, proxy, packet inspector, and logging path. An intermediary that drops properties or a client that logs only “connection failed” can erase the expected value.

Migration steps

  1. Inventory protocol version by hardware model, firmware, SDK, gateway, and broker endpoint.
  2. Select one MQTT 5 feature with measurable operational value, such as command expiry.
  3. Define mixed-version behavior. Properties do not magically translate to 3.1.1 subscribers.
  4. Keep required business meaning in the payload while old consumers remain.
  5. Add metrics for negotiated version, connection and disconnect reasons, rejected properties, and size failures.
  6. Test malformed or duplicate properties, maximum packet sizes, receive limits, reconnect, broker restart, and failover.
  7. Release through a reversible cohort and retain a compatible 3.1.1 path until recovery is proven.

Failure modes

A 3.1.1 consumer cannot receive MQTT 5 properties. User Properties can become an unbounded metadata channel unless count and bytes are capped. An unexpectedly low Receive Maximum can throttle a subscriber. Session state can outlive product expectations when Session Expiry is copied without an explicit retention policy. A redirected client still needs trust validation and an allow-list for Server Reference. Negative reason codes must reach operators; treating every acknowledgement as success wastes a central benefit of MQTT 5.

Mixed fleets also create semantic drift. If a new publisher relies on Message Expiry while an old bridge republishes without equivalent expiry, stale data can reappear. Record which hop consumed, preserved, or discarded each property in the architecture.

Implementation checklist

  • The migration names MQTT 5 properties that solve defined problems.
  • Every client, gateway, broker, and diagnostic tool is inventoried.
  • Mixed 3.1.1 and 5 delivery behavior is documented.
  • Required business fields remain in payloads during mixed operation.
  • Property count, packet size, receive maximum, and session expiry are bounded.
  • Negative acknowledgements and disconnect reasons reach observability.
  • Rollback to 3.1.1 preserves compatible session and message state.

Evidence to retain

Keep packet captures for one successful and one rejected connection per supported version, the negotiated feature matrix, mixed-version integration results, and rollback notes. Record broker, client, and gateway versions with each result. For every MQTT 5 feature, name the fallback seen by a 3.1.1 consumer and the metric that proves the feature is working. Re-run these cases when an SDK or broker changes, because a protocol-compatible upgrade can still alter defaults, persistence, logging, or property limits. The migration is complete only when the old path can be retired without hiding devices that never adopted the new version.

Primary sources

Compare the normative MQTT 3.1.1 specification with the MQTT 5.0 specification. The OASIS documents define wire behavior. Broker and SDK documentation is still required for listener configuration, persistence limits, downgrade behavior, and the reason codes exposed through logs and metrics.