What Is the MQTT Retain Handling Option?
Retain handling is a small MQTT 5 subscription option with an outsized effect on reconnect behavior: it decides whether subscribing delivers the topic's existing retained message, always, never, or only if the subscription is new. For a SCADA client that reconnects and resubscribes constantly on a flaky link, choosing the wrong value means either missing the current value or getting flooded with it. This page explains the three settings and when each is right.
MQTT Retain Handling Option in one line: The MQTT retain handling option is set per subscription in MQTT 5 and controls whether the broker sends the topic's currently retained message at subscribe time. Value 0 always sends it, value 1 sends it only if this subscription did not already exist, and value 2 never sends it. It exists so a reconnecting client can avoid re-receiving a retained value it already has.
The Three Settings and What They Do
Retain handling is one of the subscription options carried on each topic filter in an MQTT 5 SUBSCRIBE, alongside the no-local and retain-as-published flags. Its default, value 0, preserves classic MQTT behavior: when you subscribe to a topic that has a retained message, the broker immediately delivers that retained value so you get the last-known state right away. For a brand-new subscriber this is exactly what you want, an instant snapshot of current state.
Value 1 is the subtle and useful one. It says: send the retained message only if this subscription did not already exist on my session. If the client had already subscribed to this topic and is merely reasserting the subscription, the broker skips the retained delivery. This is aimed squarely at the resubscribe-after-reconnect case, where a client with a persistent session that briefly dropped does not need the broker to re-push a retained value it received moments ago and still holds.
Value 2 says never send the retained message on subscribe. The client will still receive future updates published to the topic, but it does not want the pre-existing retained snapshot at all. This suits a consumer that only cares about changes from now forward, or one that gets its baseline state through some other channel and would find the retained value redundant or confusing. Choosing among the three is a decision about what a subscribe should mean for state you may already hold.
Choosing Retain Handling on a Flaky Link
The setting matters most for a client that reconnects often, which describes almost any SCADA consumer or gateway on cellular. With a persistent session and retain handling at the default 0, every reconnect and resubscribe re-delivers every retained value the client subscribes to. On a broad wildcard covering thousands of tags, that is a flood of retained messages on every reconnect, most of them values the client already had, which wastes the link and the client's processing right when it is trying to recover.
Setting retain handling to 1 on those resubscriptions cures the flood. Because the client's session already carried the subscription, the broker recognizes the resubscribe and withholds the retained values, delivering only genuine new updates. The client keeps the current state it already held across the brief disconnect and receives only what actually changed. This pairs naturally with a well-chosen session expiry so the session survives short outages in the first place.
The judgement flips for a cold start. When a client connects clean with no prior session, or after its session has expired, it genuinely needs the retained snapshot to establish current state, so value 0 is correct there. A robust client therefore keys its retain handling on how it connected: request retained values on a fresh session to bootstrap state, and suppress them on a resubscribe within an existing session to avoid re-flooding. Getting this right is a large part of making reconnection cheap on a bad link.
Frequently Asked Questions
Is retain handling available in MQTT 3.1.1?
No. Retain handling is an MQTT 5 subscription option. Under MQTT 3.1.1 a subscribe always delivers the topic's retained message, with no way to suppress it on a resubscribe, which is why a 3.1.1 client that reconnects and resubscribes over a broad wildcard is re-flooded with retained values every time. The ability to withhold retained messages on an existing subscription is one of the MQTT 5 refinements that specifically helps clients on flaky links recover cheaply.
Does retain handling stop me getting future updates?
No. Retain handling only affects whether the broker sends the already-retained message at the moment you subscribe. Regardless of which value you choose, once subscribed you continue to receive all future messages published to the matching topics, including future retained publishes. Value 2, never send on subscribe, suppresses only the pre-existing snapshot; it does not mute the live stream. So a client that sets value 2 still tracks the topic going forward, it just does not receive the historical last-known value at subscribe time.
Sources and verification
This page references the protocol specifications published by the organizations below. Editions, product capabilities, and documentation change over time - confirm current requirements and specifications directly with the source.
- MQTT Version 5.0 (OASIS Standard) - OASIS (v5.0, 2019)
Merobix is not affiliated with, endorsed by, or sponsored by these organizations; their names are used only to identify the standards and products discussed.
Automation services
Need help turning this into a working system?
Merobix integrates SCADA, programs Allen-Bradley and Siemens PLCs, and designs and fabricates industrial control panels.
Meeting requests are reviewed before confirmation.