MQTT 5.0 introduces subscription options that give clients fine-grained control over how they receive messages. You can set the maximum quality of service (QoS) level for incoming messages, prevent receiving your own published messages, and control how the broker handles retained messages. These options are configured per topic in the SUBSCRIBE packet.
MQTT 3.1.1 only supports the QoS subscription option. The three additional options -- No Local, Retain As Published, and Retain Handling -- are available only in MQTT 5.0. Their default values preserve backward compatibility with MQTT 3.1.1 behavior.
Subscription options at a glance
| Option | Purpose | Default |
|---|---|---|
| QoS | Sets the maximum QoS level at which the broker forwards messages to the subscriber. | 0 |
| No Local | Prevents the client from receiving messages it published itself. | 0 (disabled) |
| Retain As Published | Controls whether the broker preserves the RETAIN flag on forwarded messages. | 0 (RETAIN flag cleared) |
| Retain Handling | Determines when the broker sends retained messages to the subscriber. | 0 (send on every subscribe) |
QoS level
The QoS subscription option defines the maximum QoS level the broker uses when forwarding messages to a subscriber. It does not restrict the QoS level that publishers use when sending messages.
When a publisher sends a message at a higher QoS level than the subscriber requested, the broker downgrades the message QoS before forwarding. The effective QoS is:
Effective QoS = min(Publisher QoS, Subscriber QoS)For example, if a publisher sends a message at QoS 2, and the subscriber subscribed at QoS 1, the broker forwards the message at QoS 1.
QoS levels
| Level | Delivery guarantee | Typical use case |
|---|---|---|
| QoS 0 | At most once. The message may be lost. No acknowledgment or retry. | High-frequency sensor readings where occasional data loss is acceptable, such as periodic temperature or humidity reports. |
| QoS 1 | At least once. The message is guaranteed to arrive but may be delivered more than once. | Commands and notifications that must be delivered, such as remote control instructions or alert triggers. |
| QoS 2 | Exactly once. The message arrives once and only once through a four-step handshake (PUBLISH, PUBREC, PUBREL, PUBCOMP). Higher overhead than QoS 0 and QoS 1. | None. |
QoS 2 has higher overhead than QoS 0 or QoS 1. Choose the lowest QoS level that meets your reliability requirements.
No Local
The No Local option controls whether a client receives messages that it published itself.
| Value | Behavior |
|---|---|
| 1 (true) | The client does not receive messages it published to the subscribed topic. |
| 0 (false) | The client receives all messages on the subscribed topic, including its own. This is the default and matches MQTT 3.1.1 behavior. |
When to use No Local
MQTT bridge setups. When two MQTT brokers subscribe to each other's topics to forward messages between clusters, a message forwarded from Broker A to Broker B can match Broker A's own subscription on Broker B. Without No Local, Broker B forwards the message back to Broker A, creating an infinite forwarding loop. Set No Local to 1 on both bridge subscriptions to prevent this loop.
Shared-display applications. In collaborative editing or dashboard applications, a client that publishes an update already reflects that change locally. Set No Local to 1 to avoid processing the same update twice.
Retain As Published
The Retain As Published option controls whether the broker preserves the original RETAIN flag when forwarding messages to subscribers.
| Value | Behavior |
|---|---|
| 1 (true) | The broker forwards the message with the RETAIN flag unchanged. The subscriber sees whether the publisher originally set the RETAIN flag. |
| 0 (false) | The broker clears the RETAIN flag before forwarding. The subscriber cannot distinguish retained messages from live messages. This is the default. |
When to use Retain As Published
Set this option to 1 when your application needs to differentiate between a retained message (stored by the broker and delivered upon subscription) and a live message (published in real time). For example, a monitoring dashboard might display retained messages with a "last known value" indicator while treating live messages as current readings.
Retain Handling
The Retain Handling option controls when the broker sends retained messages to a subscriber.
| Value | Behavior |
|---|---|
| 0 | Send retained messages every time the client subscribes, including resubscriptions. This is the default. |
| 1 | Send retained messages only on new subscriptions. If the client resubscribes to a topic it already subscribes to, the broker does not resend the retained message. |
| 2 | Never send retained messages, regardless of whether the subscription is new or existing. |
When to use Retain Handling
Retain Handling = 0 (default): The client needs the latest retained value on every subscription attempt, such as after a reconnect with a clean session.
Retain Handling = 1: The client maintains a persistent session and only needs retained messages for topics it subscribes to for the first time. This avoids duplicate retained messages on reconnect.
Retain Handling = 2: The client only needs live messages published after the subscription is established, not historical retained values.
Use cases
| Goal | Recommended options |
|---|---|
| Limit incoming message QoS to reduce bandwidth on constrained devices | Set QoS to the maximum level the device can handle (for example, QoS 0 for a battery-powered sensor). |
| Prevent message loops in MQTT bridge deployments | Set No Local to 1 on both bridge subscriptions. |
| Distinguish retained messages from live messages in a monitoring application | Set Retain As Published to 1. |
| Skip retained messages on reconnect to avoid processing stale data | Set Retain Handling to 1 or 2, depending on whether the subscription is new or existing. |
Example
A temperature monitoring client subscribes to sensors/temperature with the following requirements:
Receive messages at QoS 0 to minimize overhead on a constrained network.
Ignore messages published by the client itself (the client both reads and writes to this topic).
The SUBSCRIBE packet for this configuration:
SUBSCRIBE
Topic Filter: sensors/temperature
Subscription Options:
QoS: 0
No Local: 1
Retain As Published: 0
Retain Handling: 0How the broker handles this subscription:
QoS: 0 -- The broker forwards messages at QoS 0, even if the publisher sent them at QoS 1 or QoS 2. This reduces network overhead for the subscriber.
No Local: 1 -- The broker filters out messages published by this client's own client ID.
Retain As Published: 0 -- The broker clears the RETAIN flag on forwarded messages.
Retain Handling: 0 -- The broker sends retained messages every time the client subscribes, including on resubscriptions after a reconnect.
Subscription options allow you to manage topic subscriptions on clients based on your business requirements and resource restrictions. This makes MQTT 5.0 more flexible and adaptable to various scenarios and requirements.