Session State Management
Last updated:2026-01-30 14:59:40
Session State Management
Last updated: 2026-01-30 14:59:40
Feature Introduction
A session (Session) is the core mechanism in the MQTT protocol for maintaining "state" between clients and servers. By managing session state, MQTT ensures that business messages are not lost and subscriptions do not need to be rebuilt after network disconnections and reconnections, thereby guaranteeing message continuity and reliability.
This article will provide a detailed explanation of the specifications, lifecycle, and best practices for session state management in the MQTT 3.1.1 and MQTT 5.0 protocols.
Session State Definition
In the MQTT protocol, when a client (Client) establishes a connection with a server (Server), a "session" is enabled. A session exists not only during the network connection's active period; depending on the configuration, it can also persist after the network connection is disconnected. A persistent session typically contains the following data:
Subscription
Persistent sessions retain the client's subscription information: after the client reconnects, it restores the previously subscribed Topic Filter.
Consumption Progress
For normal subscriptions: After the client reconnects, it resumes the previous consumption progress and receives the earliest unconsumed message from the messaging system. Messages generated while the client is offline can still be consumed normally.
For shared subscriptions: The consumption progress is retained throughout the lifecycle of the shared group. As long as there are active sessions within this shared group, the current consumption progress will be preserved. For details, refer to Configuring Shared Subscriptions.
Session Expiration Time
MQTT 3.1 and 3.1.1 define the Session lifecycle through clean-session. When clean-session = true, the Session lifecycle aligns with the transport layer lifecycle. When clean-session = false, the Session is independent of the transport layer lifecycle. To avoid resource wastage, the product defines that after transport layer disconnection, the maximum Session retention period is 3 days.
As defined by the MQTT 5.0 protocol, the following semantics are equivalent:
MQTT 3.1,3.1.1 | MQTT 5 | |
clean-session = true | clean-start = true | session-expiry-interval = 0 |
clean-session = false | clean-start = false | session-expiry-interval = 259200 (session retention for 3 days). |
Sessions that exceed the validity period will be reclaimed. Upon the client's subsequent connection, it will be processed as a first connection.
Use Cases
Mobile Applications and Instant Messaging
Scenario description: Apps running on mobile devices (such as smart home apps, food delivery rider apps, and instant messaging (IM) applications). These applications frequently experience connection interruptions due to background switching, network transitions (4G/Wi-Fi), or screen deactivation. Users expect to immediately receive missed notifications or messages from the offline period upon reopening the App.
Recommended configuration:
MQTT 3.1.1:Clean Session = true
MQTT 5.0: Clean Start = false, Session Expiry Interval = [a longer value, such as 1 day]
Core value: Message loss prevention during roaming. Leveraging the persistent sessions mechanism, messages during the App's offline period are automatically cached on the server. When users reopen the App (reconnect), they can instantly retrieve unread messages without resubscribing to Topics, delivering a smooth user experience.
Over-the-Air Firmware Update
Scenario description: The server sends "firmware upgrade" commands in batches to millions of devices. Due to the large number of devices, some may be either offline or rebooting during the upgrade process.
Recommended configuration:
MQTT 3.1.1:Clean Session = false
MQTT 5.0: Clean Start = false, Session Expiry Interval = [a longer value, such as 1 day]
Core value: Asynchronous decoupling. Ops personnel only need to issue the upgrade command once, without needing to care whether devices are currently online. Online devices receive the command immediately; offline devices retrieve the upgrade command upon their next connection (for example, after reboot completion or network restoration). This eliminates the need for Ops personnel to repeatedly retry sending commands.
Low-Power Devices
Scenario description: Battery-powered devices (such as water meters, gas meters, and agricultural sensors). To conserve power, these devices remain in deep sleep mode (disconnected) most of the time, waking up only a few times daily to report data before immediately disconnecting.
Recommended configuration:
MQTT 3.1.1:Clean Session = true
MQTT 5.0:Clean Start = true, Session Expiry Interval = 0
Core value: Resource efficiency. The primary behavior of such devices is "unidirectional upload," typically not requiring reception of downstream commands from the server. Using non-persistent session mode ensures no unnecessary state is retained after device disconnection.
Real-Time Dashboards and Other Information Display Devices
Scenario description: Information display devices such as Web dashboards accessed by Ops personnel via browsers, advertising screens, ordering kiosks, and POS terminals.
Recommended configuration:
MQTT 3.1.1:Clean Session = true
MQTT 5.0:Clean Start = true, Session Expiry Interval = 0
Core value: On-demand usage. Information for these clients is typically highly time-sensitive and does not require historical messages. Their Client IDs are usually randomly generated (such as, web_client_uuid). After the device is closed, this ID becomes obsolete with no need to retain session state.
Billing Instructions
Message Queue MQTT edition restricts the number of connections based on different specifications. Both online sessions and offline persistent sessions occupy one connection. When the number of connections reaches the upper limit, new connections will be rejected. For details, see Billing Overview.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No
Feedback