How to Fix MQTT Retained Message Problems

Back to Blog

First Checks

Confirm the symptom is actually about retention before chasing it. Retained problems appear on subscribe: a client connects, immediately receives a value it did not expect, and that value does not change. If the value updates normally once live data flows, the issue is the retained snapshot delivered at connect time, not the live stream. Subscribe fresh with a clean session and watch what arrives in the first moment.

Check whether the topic even carries a retained message. A quick way is to subscribe and see if a value arrives before any new publish occurs; anything delivered instantly on subscribe with the retain flag set is the retained message. Ground yourself in the mechanism with the MQTT retained message before deciding which cause applies.

Fix a Stale Retained Value

A stale retained value happens when the publisher set the retain flag once, then stopped publishing - so the broker keeps handing every new subscriber that old snapshot forever. The dashboard shows a plausible but frozen number. The test: compare the retained value's timestamp, if the payload carries one, against now. A large gap confirms staleness.

The fix is to make the publisher republish current values with the retain flag on its normal cadence, so the retained snapshot is always recent. If a value is genuinely not changing but is real, a periodic retained heartbeat keeps the snapshot fresh. Do not solve this by having subscribers ignore retained messages, because then a legitimately new subscriber gets nothing until the next live publish.

Clear a Ghost Reading From a Departed Device

When a device is decommissioned or repurposed, its last retained message lives on at the broker and keeps handing new subscribers a reading for equipment that is gone. This is the ghost reading. The fix is explicit: publish a zero-byte payload to the exact same topic with the retain flag set. A retained message with an empty payload tells the broker to delete the retained message for that topic.

The empty-payload publish must go to the identical topic string, character for character, or you create a second retained topic instead of clearing the first. Getting the topic wrong here is the most common reason a clear appears to do nothing. Careful topic design up front reduces these orphans - see designing MQTT topics for an oilfield fleet.

Fix a Retained Message That Will Not Clear

If a zero-byte publish did not clear the retained message, check three things. First, the retain flag must be set on the clearing publish; an empty payload without the retain flag is just a normal empty message and clears nothing. Second, the topic must match exactly. Third, confirm the publish reached the broker at all - a QoS 0 clear on a flaky link may have been lost.

Publish the empty retained message at QoS 1 so you get an acknowledgement that the broker received it, then reconnect a subscriber and confirm no retained value arrives on that topic. If it still arrives, you cleared the wrong topic or the flag was not set. This verification loop - clear, reconnect, check - is the only way to be sure the ghost is truly gone.

When to Escalate

If retained messages behave inconsistently across subscribers, or a cleared topic reappears, suspect a broker cluster or bridge replicating retained state between nodes. In a bridged topology, a retained message cleared on one broker can be re-seeded from another that still holds it. That is a topology problem, not a client one, and belongs with whoever runs the broker fabric - see the MQTT bridge.

Escalate to the broker administrator with the exact topic, the payload you published to clear it, the QoS you used, and evidence it did not clear. On a managed broker you may not control retention policy or clustering, so a precise report is worth more than repeated clear attempts that cannot succeed against a replication you cannot see.

Common Mistakes

The top mistake is clearing a retained message with an empty payload but forgetting the retain flag, so nothing is deleted. The second is a topic-string mismatch that clears a topic no one was reading while the ghost lives on under the real one.

Another is treating a stale retained value as a live-data bug and debugging the publisher's connection when the publisher is simply not republishing. And do not disable retained messages wholesale to dodge these problems: you lose the instant-value-on-connect behavior that makes dashboards usable, trading a manageable trap for a worse one.

Frequently Asked Questions