MQTT 5 vs MQTT 3.1.1: the differences that matter
MQTT 5 keeps the publish/subscribe model of MQTT 3.1.1 but adds reason codes on every acknowledgement, properties such as user properties and message expiry, session expiry, shared subscriptions, topic aliases, request/response and flow control. Both are OASIS standards and a broker can serve both versions at the same time, so clients can move to MQTT 5 one by one.
What is the difference between MQTT 5 and MQTT 3.1.1?
MQTT 5 is a revision of MQTT 3.1.1 that keeps the same core model and adds better error reporting, metadata and control over sessions and load. Topics, wildcards, QoS 0/1/2, retained messages and Last Will work the same way in both versions.
MQTT 3.1.1 became an OASIS standard in 2014 and was later published as ISO/IEC 20922. MQTT 5.0 became an OASIS standard in 2019. There is no MQTT 4: the protocol level byte in the CONNECT packet is already 4 for MQTT 3.1.1, so the new version took the number 5.
The biggest structural change is properties. Most MQTT 5 packets carry an optional list of properties in the variable header. Nearly every new feature is a property.
The table lists the changes engineers run into most often.
| Feature | MQTT 3.1.1 | MQTT 5 |
|---|---|---|
| Acknowledgements | Return codes only in CONNACK and SUBACK | Reason codes in CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT and AUTH |
| Session control | Clean Session flag | Clean Start flag plus Session Expiry Interval |
| Message lifetime | Messages wait until delivered | Message Expiry Interval per message |
| Custom metadata | Only in the payload | User Properties (key/value pairs) |
| Load balancing | Not in the standard | Shared subscriptions: $share/<group>/<filter> |
| Header size | Full topic name in every PUBLISH | Topic aliases replace the name with a number |
| Request/response | Convention only | Response Topic and Correlation Data properties |
| Flow control | Not defined | Receive Maximum limits unacknowledged QoS 1/2 messages |
| Packet size limit | Not negotiated | Maximum Packet Size, announced by client and server |
| Server disconnect | Server closes the connection silently | Server can send DISCONNECT with a reason code |
| Authentication | Username and password in CONNECT | Adds an AUTH packet for challenge/response methods |
| Subscription options | QoS only | QoS, No Local, Retain As Published, Retain Handling |
| Payload description | None | Payload Format Indicator and Content Type |
Reason codes and server-sent DISCONNECT
MQTT 5 tells a client why something failed, not just that it failed. In MQTT 3.1.1, a PUBACK has no status. If the broker refuses a publish, for example because the client is not authorised for that topic, the usual reaction is to close the connection. The client has to guess the cause.
In MQTT 5, every acknowledgement carries a reason code. Codes below 0x80 mean success, codes from 0x80 upwards mean failure. A PUBACK can report “Not authorized” (0x87) or “No matching subscribers” (0x10). The server can also send a DISCONNECT packet with a reason such as “Session taken over” or “Keep Alive timeout” before it closes the connection. An optional Reason String property adds human-readable text for diagnostics.
Sessions and message expiry
MQTT 5 separates “start fresh” from “how long to keep state”. In MQTT 3.1.1, Clean Session = 0 means the broker keeps the session, with its subscriptions and queued QoS 1/2 messages, with no defined end. On large fleets this leaves state behind for devices that never return.
MQTT 5 splits this into two settings:
- Clean Start: if set, the broker discards any existing session at connect.
- Session Expiry Interval: the number of seconds the broker keeps the session after the connection closes. 0 means the session ends with the connection; 0xFFFFFFFF means it does not expire.
The Message Expiry Interval works per message. If a message waits in a queue longer than its interval, the broker drops it instead of delivering stale data. A related property, the Will Delay Interval, lets the broker wait before it publishes a Last Will, so a short network drop does not trigger an offline alarm.
Shared subscriptions and subscription options
Shared subscriptions let several clients split the messages of one subscription between them. A client subscribes to $share/<group>/<filter>, and the broker delivers each matching message to only one member of the group:
$share/ingest/plant/+/temp
Three instances of a backend service subscribing to this filter each receive part of the stream. This is the standard way to scale consumers horizontally.
MQTT 5 also adds three subscription options:
- No Local: the client does not receive its own publications on this subscription.
- Retain As Published: the retain flag is forwarded as the publisher set it, which bridges need.
- Retain Handling: controls whether retained messages are sent at subscribe time (0 = always, 1 = only for a new subscription, 2 = never).
Topic aliases, flow control and packet size
These features protect bandwidth and memory on constrained links and busy brokers.
Topic aliases
A sender can map a topic name such as enterprise/site-frankfurt/line-3/press-07/temp to a small integer and then send only the integer in later PUBLISH packets. Each side announces how many aliases it accepts with Topic Alias Maximum. Aliases are valid only for the current network connection.
Receive Maximum
Each side announces how many QoS 1 and QoS 2 messages it is willing to have unacknowledged at once. The sender must not exceed that number, which gives simple back-pressure.
Maximum Packet Size
Client and server can announce the largest packet they accept. A server must not send a larger packet to that client, so a small device is not overwhelmed by an oversized payload.
Request/response, user properties and enhanced authentication
MQTT 5 standardises patterns that teams previously built by convention.
Request/response: the requester publishes with a Response Topic and Correlation Data. The responder publishes its reply to that topic and copies the correlation data, so the requester can match replies to requests.
User properties: any number of UTF-8 key/value pairs on most packets. On PUBLISH they are forwarded to subscribers. Teams use them for trace IDs, units or schema versions.
Enhanced authentication: the CONNECT packet can name an Authentication Method, and client and server can exchange AUTH packets for challenge/response schemes. The client can also re-authenticate during a live connection.
Should you upgrade to MQTT 5?
For new systems, MQTT 5 is usually the better default because errors are visible and sessions, load and message lifetime can be controlled. Migration can be gradual: a broker that supports both versions lets 3.1.1 and 5 clients exchange messages on the same topics. Check that your client libraries and broker support the MQTT 5 features you plan to use, and keep MQTT 3.1.1 where a device cannot be updated.