MQTT 5.0: What's New vs MQTT 3.1.1

Quick answer

MQTT 5.0 is the latest version of the protocol. It keeps the lightweight pub/sub core of 3.1.1 and adds reason codes, user properties, topic aliases, shared subscriptions, message and session expiry, and flow control — giving you far better error reporting and control.

MQTT 5.0 is the current version of the protocol, released in 2019. It doesn't reinvent MQTT — the lightweight pub/sub core is unchanged — but it fills in the gaps that large, production IoT deployments kept running into: opaque errors, no per-message metadata, and no built-in flow control.

What MQTT 5.0 adds

Reason codes & reason strings Acknowledgements now explain why something failed, instead of a bare success or fail. User properties Attach custom key/value metadata to messages and packets, like application-level headers. Payload format & content type Flag a payload as UTF-8 text or bytes and label it with a MIME-like content type. Session & message expiry Bound how long a session survives after disconnect and how long a queued message stays valid. Topic aliases Replace a long topic string with a short integer for the rest of a connection, cutting bandwidth. Flow control A client advertises how many unacknowledged messages it will accept, so the broker can’t overwhelm it. Shared subscriptions Standardized load balancing across a group of consumers. Request / response A response-topic and correlation-data convention for RPC-style exchanges over pub/sub.

5.0 turns an opaque failure code into a precise, human-readable reason

Should you upgrade from 3.1.1?

For new projects, prefer 5.0 — the diagnostics and control alone are worth it, and libraries and brokers broadly support it. Because the two versions share the same model, most deployments migrate gradually, running 3.1.1 and 5.0 clients against the same broker until everything is moved over.

MQTT 5.0 in TBMQ

TBMQ supports the full range of MQTT 3.1, 3.1.1, and 5.0 on the same broker. Its 5.0 implementation includes reason codes, user properties, topic aliases, session and message expiry, flow control, enhanced authentication, and the subscription options and identifiers from the spec. See the MQTT protocol guide for the complete list of supported 5.0 features.

Frequently asked questions

What is the difference between MQTT 5.0 and MQTT 3.1.1?

MQTT 5.0 keeps the same lightweight publish/subscribe core as 3.1.1 but adds richer control and diagnostics: reason codes and reason strings on every acknowledgement, user properties (custom metadata), topic aliases, session and message expiry, flow control, and standardized shared subscriptions.

Is MQTT 5.0 backward compatible with 3.1.1?

Not on the wire — the packet formats differ, so a client and broker must agree on the version at connect. But the model is the same, and brokers like TBMQ speak both, so 3.1.1 and 5.0 clients can run against the same broker side by side during a migration.

What are user properties in MQTT 5.0?

Arbitrary key/value pairs you can attach to messages and control packets, similar to HTTP headers. They let you carry application metadata — a message type, a tenant ID, a trace token — without encoding it into the topic or payload.

What are reason codes in MQTT 5.0?

Numeric result codes returned on acknowledgements (CONNACK, PUBACK, SUBACK, DISCONNECT, and more), often with a human-readable reason string. In 3.1.1 a failure was largely opaque; in 5.0 the broker can say exactly why something was refused.

Should new projects use MQTT 5.0?

Generally yes. New deployments benefit from the better error reporting, expiry controls, and flow control, and all current major brokers support it. Choose 3.1.1 only when a constrained device or library you must use does not implement 5.0.

Run it yourself

TBMQ is a free, open-source MQTT broker built to scale. Spin it up in minutes or try the live demo — no install required.

Try it now Live demo