MQTT retained messages

How retained messages work

• One retained message per topic. A new retained publish replaces the old one.
• It is delivered to every new subscriber with the retain flag set, before any live traffic.
• It outlives the client that sent it and survives broker restarts where persistence is on.
• An empty retained publish deletes it.

Device state topics, Home Assistant MQTT discovery configs and Sparkplug STATE messages all rely on retain. Commands should not: a retained command runs again on every subscriber restart.

Problems stale ones cause

• Ghost devices. A sensor removed months ago still appears because its discovery config and last state are retained.
• Stale readings that look live. Every new subscriber gets an old value the moment it connects.
• Test debris. A load test that retained on thousands of topics leaves them there indefinitely.
• Replayed commands. A retained command topic fires on every reconnect.

How to clear a retained message

1. Find the topic. Subscribe to a wildcard above it and watch what arrives at once with the retain flag set. In MQTT Viewer's topic tree retained topics carry a marker.
2. Publish an empty retained message to the exact topic. With the mosquitto client:

   mosquitto_pub -h broker.example.com -t 'your/topic' -r -n

   In MQTT Viewer, right-click the topic and choose Clear retained message, or publish with an empty payload and Retain ticked.
3. Check it is gone. Subscribe again from a fresh client. Nothing arrives at once, so the store is clear.

Clearing many at once

MQTT has no broker-wide delete. Each topic needs its own empty retained publish. Three ways to do it in bulk:

• Script it: subscribe with a wildcard, collect the retained topics, publish empty to each.
• On mosquitto, stop the broker and delete its persistence file. Everything retained goes, along with queued messages for persistent sessions.
• In MQTT Viewer, right-click a branch and choose Clear retained messages below. The confirmation shows how many topics it knows about, then clears each one.

Details worth knowing

• The clearing publish is delivered. Current subscribers receive the empty message, which is a useful state-gone signal. The broker stores nothing afterwards.
• MQTT 3 hides mid-session retains. Under 3.1.1 the retain flag is only guaranteed on messages replayed at subscribe time. A message retained while a client is already subscribed arrives looking ordinary, so no MQTT 3 client can promise it has seen every retained topic. MQTT 5's Retain As Published option fixes this.
• QoS 0 retained messages can vanish on restart on some brokers, while QoS 1 and 2 survive. Retain at QoS 1 when persistence matters.
• Retained is not queued. Retained messages serve future subscribers. Queued messages serve a disconnected persistent session. Different mechanisms.

Frequently asked questions

Related: MQTT QoS levels, $SYS topics, and the MQTT cheat sheet. The Home Assistant guide covers clearing stale discovery configs.