MQTT retained messages: how they work and how to clear them
A retained message is an MQTT message published with the retain flag set. The broker stores the last retained message for each topic and sends it immediately to every new subscriber of that topic, so a client gets the current value without waiting for the next publish. Publishing an empty payload with the retain flag to the same topic deletes the stored message.
What a retained message is
A retained message is a normal MQTT PUBLISH with the retain flag set to 1. The broker delivers it to current subscribers as usual, and also stores it as the last known value of that topic. When a client later subscribes to a matching topic filter, the broker sends the stored message right after the subscription.
Without retain, a new subscriber sees nothing until the publisher sends again. For a value that changes rarely, such as a machine state or a configuration, that can mean waiting minutes or hours. With retain, a dashboard that opens at any time shows the current state at once.
mosquitto_pub -h broker.example.com -t 'plant/line-3/press-07/state' -m 'running' -r
Any client that subscribes later receives running immediately:
mosquitto_sub -h broker.example.com -t 'plant/line-3/+/state' -v
The rules for retained messages
The MQTT 3.1.1 and 5.0 standards define a small set of rules.
| Rule | What it means in practice |
|---|---|
| One retained message per topic | A new retained message replaces the previous one on the same topic |
| Delivered on subscribe | Every new matching subscription receives the stored message |
| Wildcards match retained messages | A subscription to plant/# receives the retained message of every matching topic |
| Empty payload clears | A retained PUBLISH with a zero-byte payload deletes the stored message |
| Stored independently of sessions | Retained messages stay on the broker after the publisher disconnects |
| QoS is kept | The stored message is delivered at the lower of its QoS and the subscription QoS |
A retained message is tied to a topic, not to a client. It stays on the broker until someone replaces or clears it, even if the original publisher never connects again. In MQTT 5.0 it can also expire (see below).
Retained messages with QoS 0 are protected less strictly. MQTT 3.1.1 explicitly allows the broker to discard a stored QoS 0 retained message at any time. Use QoS 1 for retained state that must not be lost.
How to clear a retained message
To delete a retained message, publish a message with the retain flag and an empty payload to the same topic. The broker removes the stored message and does not store the empty message in its place.
mosquitto_pub -h broker.example.com -t 'plant/line-3/press-07/state' -r -n
The -n flag sends a zero-length payload. Note that a payload of "" or a single space is not empty. The message must have zero bytes.
Clearing does not work with wildcards, because you cannot publish to a topic filter. To clean up many retained messages, subscribe with a wildcard to list the topics, then clear each topic one by one.
How subscribers recognise retained messages
A subscriber can tell from the retain flag on the incoming PUBLISH whether it received a stored value or a live message. When a message is sent because a new subscription was made, the broker sets the retain flag to 1. When a message is forwarded to an existing subscriber in normal operation, MQTT 3.1.1 sets the retain flag to 0, even if the publisher set it.
This lets an application treat the first value as “current state on startup” and later values as live changes. With mosquitto_sub, the -R option suppresses messages that arrive with the retain flag set, so you only see live traffic.
mosquitto_sub -h broker.example.com -t 'fleet/+/soc' -R -v
Retained message options in MQTT 5.0
MQTT 5.0 adds three controls that make retained messages easier to use at scale.
Retain As Published
Retain As Published is a subscription option. If it is set, the broker forwards messages with the retain flag as the publisher set it, instead of clearing it. This matters for bridges between brokers, which need to know which messages should be retained on the other side.
Retain Handling
Retain Handling is a subscription option with three values:
| Value | Behaviour |
|---|---|
| 0 | Send retained messages when the subscription is made (default, same as MQTT 3.1.1) |
| 1 | Send retained messages only if the subscription did not already exist |
| 2 | Do not send retained messages for this subscription |
Value 1 avoids receiving the same retained values again when a client renews a subscription it already has.
Message Expiry Interval
A publisher can set a Message Expiry Interval in seconds. For a retained message, the broker stops delivering it once the interval has passed. This prevents new subscribers from receiving a value that is long out of date, for example the last position of a vehicle that went offline a week ago.
The broker can also tell clients in CONNACK that it does not support retained messages at all, through the Retain Available property.
When to use retained messages
Use retained messages for state, not for events. A good test: if a new subscriber needs to know the latest value immediately, retain it.
Good candidates:
- Machine or device state:
running,stopped,fault - Online status, often together with a retained Last Will that sets
offline - Configuration and setpoints
- Slow-changing measurements, such as the state of charge on
fleet/ev-0042/soc - The current values in a Unified Namespace, where every consumer expects to see the latest state of
enterprise/site-frankfurt/line-3/press-07/temp
Poor candidates:
- Events and alarms that should be seen once, not replayed to every new subscriber
- Commands, because a retained command would be executed again by every client that subscribes later
- High-rate data where no one needs the last value on subscribe
A retained message is not a history. The broker keeps only the latest value per topic. If you need earlier values, store them in a historian or database.