What Is the MQTT Message Expiry Interval?

What the Property Controls

Message expiry is set by the publisher on an individual PUBLISH packet as one of the MQTT 5 properties. It only matters when a message cannot be delivered immediately, which in practice means it has been queued for a subscriber whose session is still alive but whose network connection is currently down. For a message that is delivered right away the interval is irrelevant. It is a rule about how long a stored, undelivered message stays worth delivering.

The broker treats the interval as a countdown. It records how long the message has been waiting and, when the subscriber finally reconnects, forwards the message with the expiry interval reduced by the elapsed time. If that elapsed time exceeds the original interval, the broker discards the message and the subscriber never sees it. This is fundamentally different from the fire-and-forget of QoS 0; expiry only interacts with the queued messages that persistent sessions and QoS 1 or 2 create.

It is important not to confuse message expiry with session expiry or with retained messages. Session expiry governs how long the broker keeps a client's whole subscription and queue after it disconnects. A retained message is the last-known value the broker hands a brand-new subscriber. Message expiry is narrower than either: it is the lifetime of one specific queued publish. All three can be in play at once for the same client.

Why Stale Telemetry Is a Problem Worth Solving

Consider a gateway that publishes a tank level every few seconds at QoS 1, and a cloud consumer that briefly loses its connection. With a persistent session and no expiry, the broker faithfully queues every level reading during the outage and delivers the entire backlog the instant the consumer reconnects. The consumer now receives a burst of readings that are minutes old, in order, and if it naively writes them to a historian it records a stale value as if it were current, or it thrashes through a backlog before catching up to reality.

Setting a modest message expiry interval on those telemetry publishes changes the behavior to something a control system actually wants. During a short outage only the readings younger than the interval survive; anything older is dropped by the broker. The consumer reconnects and receives just the recent history, or in the extreme case only values still fresh enough to matter. For a live process value, delivering the current reading and discarding the stale backlog is almost always the correct trade, and it keeps the ingestion path from doing pointless work, a concern shared with MQTT to time-series database ingestion.

The judgement is per data type. Live process values want a short expiry so nobody acts on old data. Certain event or command messages want no expiry at all, because a missed setpoint change or a missed alarm acknowledgement is not something you want silently dropped just because the recipient was offline for a while. Deciding the expiry per topic, rather than applying one blanket value, is what separates a thoughtful design from a copied default.

Frequently Asked Questions