Protocol guide

MQTT Protocol Versions

A detailed guide to MQTT 3.1, MQTT 3.1.1, MQTT 5.0, MQTT-SN, compatibility, feature differences, and upgrade strategy.

Protocol versions

MQTT Protocol Versions Explained

MQTT versions are not just release labels. They determine the CONNECT packet, broker compatibility, error reporting, session lifetime, message metadata, and operational visibility. The practical MQTT version map is MQTT 3.1, MQTT 3.1.1, MQTT 5.0, plus the related MQTT-SN protocol. As of May 2026, the official OASIS MQTT directory lists v3.1.1 and v5.0 for the main MQTT standard, not MQTT 5.1.

Quick answer

Choose MQTT 5.0 for new systems when you need reason codes, properties, message expiry, request-response patterns, flow control, or better diagnostics.
Use MQTT 3.1.1 as the compatibility baseline for older devices, low-cost modules, existing SDKs, and industrial deployments.
Treat MQTT 3.1 as a historical compatibility target, not a new implementation target.
Use MQTT-SN only when the network model needs sensor-network behavior rather than normal TCP/TLS or WebSocket MQTT.

VersionStatusProtocol levelBest fitNew project guidance

MQTT 3.1Historical reference3Legacy devices, older brokers, early IBM-era compatibilityUse only when legacy clients require it

MQTT 3.1.1OASIS / ISO standard4Broad IoT compatibility, gateways, lightweight telemetrySafe compatibility baseline

MQTT 5.0OASIS standard5Modern brokers, cloud platforms, multi-tenant systems, stronger diagnosticsPreferred for new systems

MQTT-SN 1.2Related specificationSeparate protocolSensor networks, non-TCP/IP links, constrained devicesUse only when the network requires it

MQTT 3.1: historical version for legacy compatibility

MQTT 3.1 is the important pre-OASIS foundation for the protocol. Early brokers, client libraries, embedded devices, and integration guides were built around it. It already had the MQTT model most developers recognize: clients and brokers, CONNECT, PUBLISH, SUBSCRIBE, QoS 0/1/2, retained messages, will messages, keep alive, and topic filters.

The issue is not that MQTT 3.1 cannot work. The issue is that later versions clarified interoperability, naming, transport, conformance, and error behavior. In modern systems, MQTT 3.1 mostly matters because it explains historical behavior: older protocol names, older CONNECT packets, and why some brokers still expose a compatibility switch.

Do not target MQTT 3.1 for a new product. Keep it only when firmware cannot be upgraded, a field gateway only speaks 3.1, or a broker must support old clients during a migration.

Implementation and troubleshooting notes

Confirm whether the broker explicitly enables MQTT 3.1 compatibility.
Inspect the protocol name and protocol level in CONNECT packets.
Do not treat every 3.1 connection failure as a network problem; it is often protocol negotiation.

MQTT 3.1.1: the practical compatibility baseline

MQTT 3.1.1 is the first widely standardized and long-lived MQTT version. It is the common language for many IoT devices, gateways, open-source brokers, hosted brokers, and browser MQTT over WebSocket tools.

Its strength is compatibility. Low-cost cellular modules, edge gateways, PLC-adjacent devices, old mobile SDKs, and embedded clients often support MQTT 3.1.1 reliably. If your system only needs telemetry, command topics, retained messages, last will messages, and QoS, MQTT 3.1.1 is still enough.

Its limitations show up in production operations. Error reporting is coarse. There is no standard property mechanism for user metadata, content type, response topics, or correlation data. Session expiry, message expiry, flow control, server capability declaration, and disconnect diagnostics are much weaker than in MQTT 5.0.

When MQTT 3.1.1 is still the right choice

Device SDKs or modules do not support MQTT 5.0.
The message model only needs publish, subscribe, QoS, retain, and will.
Maximum broker and client compatibility matters more than protocol features.
Field upgrade cost is higher than the benefit of protocol migration.

MQTT 5.0: the modern MQTT version

MQTT 5.0 is the modern OASIS MQTT standard. It does not replace the publish/subscribe model; it extends connection, publishing, subscribing, acknowledgements, disconnects, and error handling with properties and reason codes.

The two most important additions are Properties and Reason Codes. Properties let clients and brokers express session expiry, message expiry, maximum packet size, receive windows, topic aliases, response topics, correlation data, user properties, payload format indicators, and content type. Reason codes let CONNACK, PUBACK, SUBACK, UNSUBACK, DISCONNECT, and other packets explain failures precisely.

This matters in real production systems. Operators can distinguish authentication failure, authorization failure, protocol errors, oversized packets, server migration, and administrative disconnects. Developers can build request-response flows with Response Topic and Correlation Data, avoid late stale commands with Message Expiry, attach business metadata with User Properties, and use Receive Maximum for flow control.

Important MQTT 5.0 capabilities

Reason Codes for precise connection, publish, subscribe, and disconnect feedback.
Properties for standardized message and session metadata.
Session Expiry Interval for more precise session lifetime control than clean session.
Message Expiry Interval to prevent stale commands and state messages.
Topic Alias to reduce repeated topic-name overhead.
Receive Maximum and Maximum Packet Size for backpressure and resource protection.
Response Topic and Correlation Data for request-response patterns.
User Properties, Content Type, and Payload Format Indicator for business metadata.
Server Reference and enhanced DISCONNECT semantics for migration and diagnostics.

MQTT-SN: related protocol for sensor networks

MQTT-SN, formerly MQTT-S, is not a replacement for normal MQTT over TCP. It extends MQTT-style publish/subscribe messaging to non-TCP/IP networks and constrained sensor environments such as Zigbee-style wireless sensor networks.

MQTT-SN typically introduces a gateway that maps short addresses, Topic IDs, and constrained network behavior into a normal MQTT broker world. It is useful when byte overhead, sleep cycles, and unreliable sensor links dominate the design.

If your device can use TCP/TLS or WebSocket reliably, you usually do not need MQTT-SN. Evaluate MQTT-SN when the network is not IP-based, the device is extremely constrained, or the architecture needs a sensor-network gateway.

How to choose

Cloud IoT, WebSocket testing, TCP/TLS device connections: use MQTT 3.1.1 or MQTT 5.0.
Non-TCP/IP sensor networks and sleep-heavy devices: evaluate MQTT-SN.
Sensor-network to MQTT broker integration: design the MQTT-SN gateway carefully.

How to migrate from MQTT 3.1.1 to MQTT 5.0

Confirm that the broker, device SDKs, gateways, cloud platform, and test tools all support MQTT 5.0.
Start with the highest operational value: reason codes, DISCONNECT reasons, message expiry, session expiry, and maximum packet size.
Do not make every message property-driven at once. Keep MQTT 3.1.1 semantics first, then adopt User Properties, Response Topic, and Topic Alias deliberately.
For mixed device fleets, let the broker accept both MQTT 3.1.1 and MQTT 5.0, then migrate by tenant, product line, or firmware generation.

FAQ

Is MQTT 5.0 compatible with MQTT 3.1.1?

They share the same publish/subscribe model, but the CONNECT protocol level is different. A broker can support both, but a client session uses one protocol version at a time.

Does MQTT 5.1 exist?

As of May 2026, the official OASIS MQTT main specification directory lists v3.1.1 and v5.0, not an MQTT 5.1 mainline standard.

Should every new project use MQTT 5.0?

Not always. If your devices and platform support it, MQTT 5.0 is the better default. If field devices or SDKs only support 3.1.1, MQTT 3.1.1 is the pragmatic choice.

Official references

Continue to QoS guide Open MQTT client