MQTT GUIDE
3 min readMQTT Retained Messages
A retained message is the last message the broker stored for a topic with the retain flag set. Any client that subscribes later immediately receives that last known value instead of waiting for the next publish — ideal for state like a device’s current status.
Normally a subscriber only sees messages published after it subscribes — connect a second too late and you learn nothing until the next publish. Retained messages fix that: they let the broker hand every new subscriber the current value of a topic straight away.
How the retain flag works
When a message is published with the retain flag set, the broker stores it as the last known value for that topic — replacing any previous retained value. From then on, any client that subscribes to a matching topic immediately receives that stored message, flagged as retained, before any live traffic. Publishing an empty payload with the retain flag clears the stored value.
What retained messages are good for
It's worth being clear about the boundary: a retained message is the current value of a topic, kept for everyone. It is not a replay log — there is only one retained message per topic. To catch up on messages a specific client missed while offline, that's a persistent session, not retention.
Retained messages in TBMQ
TBMQ keeps retained messages in an in-memory trie for fast lookup, backed by a compacted Kafka topic so they survive broker restarts. Clearing a retained message removes it from the trie, and a scheduled cleanup job prunes the empty nodes it leaves behind. See the retained messages guide for configuration and the UI view of stored retained messages.
Frequently asked questions
What is a retained message in MQTT?
A message published with the retain flag set, which the broker stores as the last known value for that topic. Any client that subscribes later receives it immediately, instead of having to wait for the next publish.
How do you clear a retained message?
Publish a message to the same topic with the retain flag set and an empty (zero-byte) payload. The broker removes the stored value, so future subscribers get nothing until a new retained message is published.
How many retained messages can a topic hold?
One. Retained storage is last-value-wins per topic — each new retained publish replaces the previous one. Retained messages are not a history or replay log; for that you need a persistent session or a streaming platform.
What is the difference between retained messages and persistent sessions?
A retained message is the current value of a topic, kept for any future subscriber. A persistent session is a per-client queue of messages missed while that specific client was offline. Retained messages serve everyone; persistent sessions serve one client’s catch-up.
Are retained messages a good fit for device status?
Yes — it is the classic use case. Publishing a device’s online/offline status or latest configuration as a retained message means any dashboard or service that connects later immediately knows the current state without waiting.
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.