MQTT 5.0 extends MQTT 3.1.1 with finer control over sessions, message delivery, and device-cloud communication. ApsaraMQ for MQTT supports both protocol versions.
For the full specifications, see MQTT 5.0 and MQTT 3.1.1.
Supported editions
The following ApsaraMQ for MQTT instance types support MQTT 5.0:
Professional Edition
Enterprise Platinum Edition
Serverless instances
To upgrade an existing instance to MQTT 5.0, submit a ticket.
Unsupported MQTT 5.0 features
ApsaraMQ for MQTT does not support:
Shared subscriptions
Will messages
Retained messages
Limitations
| Parameter | Limit | Behavior when exceeded |
|---|---|---|
| Keep Alive | 8 minutes (maximum on broker) | Capped to 8 minutes |
| Message size (broker) | 128 KB | See note below |
| Message body (send) | 64 KB | Must not exceed this limit |
| Subscription Identifier | 1 to 268,435,455 | Subscription fails and returns an error code |
| Receive Maximum (client) | 65,535 | Capped to 65,535 |
The broker does not check data packet size by default. After receiving a data packet, the broker pushes it directly without size validation. To enable size checking and intercept oversized packets, join DingTalk group 116015007918 to contact ApsaraMQ for MQTT technical support.
For feature-specific limits, see the documentation for each feature below.
MQTT 5.0 features
User properties
User properties attach custom key-value metadata (UTF-8 encoded strings) to MQTT control packets, similar to HTTP headers. They are available on all MQTT 5.0 control packets except heartbeat packets.
Use cases:
Pass application-level routing information between devices and backend services
Include timestamps, content types, or correlation IDs alongside messages
Add custom metadata without modifying the message payload
For details, see User properties.
Topic aliases
Topic aliases replace long topic name strings with short integer values to reduce packet size. This is useful for IoT devices on cellular networks where bandwidth and power consumption matter.
For example, a topic like data/region/site/building/floor/room/sensor-42/temperature/current can be mapped to a single integer alias, reducing per-message overhead.
For details, see Topic aliases.
Session expiry interval
MQTT 5.0 replaces the cleanSession flag from MQTT 3.1.1 with two separate controls: cleanStart and Session Expiry Interval. Together, they provide finer-grained session management.
MQTT 3.1.1 to MQTT 5.0 parameter mapping:
| MQTT 3.1.1 | MQTT 5.0 equivalent | Behavior |
|---|---|---|
cleanSession=true | cleanStart=true, Session Expiry Interval=0 (or absent) | Discards any existing session state and starts fresh. The session is deleted on disconnect. |
cleanSession=false | cleanStart=false, Session Expiry Interval > 0 | Restores the previous session if the client reconnects before the expiry interval elapses. |
For details, see Session expiry interval.
Message expiry interval
Set a time-to-live (TTL) on messages stored on the broker. Expired messages are automatically deleted, preventing stale commands from reaching devices after a prolonged disconnection.
For example, a control command sent to a device may lose relevance after a few minutes. With message expiry, the broker drops the command instead of delivering it late.
For details, see Message expiry interval.
Subscription options
Specify parameters such as Quality of Service (QoS) level when subscribing to a topic. These options control how the broker delivers messages and let you optimize transmission for different use cases.
For details, see Subscription options.
Request-response pattern
MQTT 5.0 adds a built-in request-response pattern for one-to-one communication. The requesting client specifies a response topic and correlation data in the PUBLISH packet. The responding client publishes its reply to that topic with matching correlation data, allowing the requester to match responses to requests.
Use this pattern when a device needs a direct reply -- for example, querying a device's current configuration and waiting for the response.
For details, see Request-response pattern.
Payload format indicator
The payload format indicator specifies whether the payload is an unstructured byte stream or a UTF-8 encoded string. This indicator helps both the publisher and subscriber interpret the data format consistently, reducing parsing errors.
For details, see Payload format indicator.
Optimized device-cloud interactions
MQTT 5.0 improves device-cloud communication with:
Connection negotiation -- Client and broker exchange capability information during the CONNECT/CONNACK handshake, allowing both sides to adapt behavior.
Detailed reason codes -- Reason codes in CONNACK, PUBACK, SUBACK, and DISCONNECT packets provide specific failure details instead of generic errors.
Broker-initiated disconnect -- The broker sends a DISCONNECT packet with a reason code before closing the connection, giving the client actionable diagnostic information.
These improvements simplify troubleshooting for device connectivity issues.
For details, see Optimized device-cloud interactions.
What's next
To start using MQTT 5.0 features, make sure your instance meets the edition requirements, then join DingTalk group 116015007918 to contact ApsaraMQ for MQTT technical support.