Skip to main content

Retained messages

A message published with RETAIN is stored as the "last known good" value for its topic and delivered to every new matching subscriber on subscribe.

  • Set — publish with RETAIN and a non-empty payload.
  • Clear — publish with RETAIN and an empty payload.

Retained messages are WAL-backed. Note that the WAL record keeps QoS, topic, payload and expiry, but not MQTT 5 User Properties or the Retain-As-Published flag — those are preserved on live delivery but lost across a restart.

Message expiry (MQTT 5)​

A publish may carry a message expiry interval. It is enforced for the retained store (expired retained values are pruned lazily when matched) and on reconnect replay (queued/inflight messages get their remaining lifetime). It is not applied on live delivery to an already-connected subscriber, and a broker-generated Will currently drops its properties (including expiry).

Retain handling (MQTT 5)​

A subscription's Retain Handling (0/1/2) controls whether retained messages are sent on subscribe: always, only for a new subscription, or never. Retain As Published controls whether the RETAIN flag is preserved on forward (live delivery only).