MQTT QoS levels explained: 0, 1 and 2
MQTT has three Quality of Service levels. QoS 0 delivers a message at most once with no acknowledgement, QoS 1 delivers it at least once and can produce duplicates, and QoS 2 delivers it exactly once using a four-packet handshake. QoS applies to each hop separately, so a subscriber receives a message at the lower of the publish QoS and its subscription QoS.
What QoS means in MQTT
QoS (Quality of Service) is the delivery guarantee for a single MQTT message between two parties. MQTT 3.1.1 and MQTT 5.0 both define the same three levels:
| Level | Guarantee | Packets exchanged | Duplicates possible | Typical use |
|---|---|---|---|---|
| QoS 0 | At most once | PUBLISH | No | Frequent sensor values, where the next reading replaces the last |
| QoS 1 | At least once | PUBLISH, PUBACK | Yes | Alarms, events, status changes that must arrive |
| QoS 2 | Exactly once | PUBLISH, PUBREC, PUBREL, PUBCOMP | No | Commands or counts where a duplicate would cause a wrong result |
Higher QoS means more packets, more state on both sides and more latency per message. It does not make the network faster or more reliable. It only defines what happens when packets or connections are lost.
QoS 0: at most once
With QoS 0 the sender sends the PUBLISH once and forgets it. There is no acknowledgement and no retry. If the TCP connection breaks while the message is in transit, the message is lost.
mosquitto_pub -h broker.example.com -t 'plant/line-3/temp' -m '72.4' -q 0
QoS 0 is often the right choice for telemetry that is published every second or every few seconds. A lost temperature reading is replaced by the next one a moment later. QoS 0 also uses the least bandwidth, which matters on cellular links.
QoS 1: at least once
With QoS 1 the sender keeps the message until it receives a PUBACK with the same packet identifier. If no PUBACK arrives, for example because the connection dropped, the sender resends the PUBLISH after reconnecting and sets the DUP flag.
The flow is:
Sender Receiver
| --- PUBLISH (id 17) --> |
| <-- PUBACK (id 17) --- |
The weak point is the lost PUBACK. The receiver already has the message, the sender does not know that, and it sends the message again. The receiver can then process the same message twice. The DUP flag only tells the receiver that this is a redelivery attempt. It does not tell the receiver whether it already saw the message.
For that reason, QoS 1 consumers should be idempotent. Common ways are to include a sequence number or timestamp in the payload, or to design messages as absolute values (soc=81) instead of deltas (soc+1).
mosquitto_pub -h broker.example.com -t 'fleet/ev-0042/soc' -m '81' -q 1
QoS 2: exactly once
With QoS 2 the sender and receiver use a four-packet handshake so that the message is delivered exactly once on that hop.
Sender Receiver
| --- PUBLISH (id 18) --> | receiver stores the packet id
| <-- PUBREC (id 18) --- | "received"
| --- PUBREL (id 18) --> | "release"; receiver may now forget the id
| <-- PUBCOMP (id 18) --- | "complete"
The receiver remembers the packet identifier from PUBLISH until PUBREL. If a duplicate PUBLISH with the same identifier arrives in that window, it is not passed on to the application again. This removes duplicates, at the cost of two round trips and stored state on both sides.
Use QoS 2 when a duplicate would cause a real error, for example a command such as “start the next batch” or a counter that is added up downstream. Many teams use QoS 1 with idempotent consumers instead, because it is simpler and has lower latency.
QoS is per hop: the effective QoS
QoS is not end-to-end. It applies separately to the hop from publisher to broker and to the hop from broker to each subscriber.
When a client subscribes, it requests a maximum QoS for that subscription. The broker grants a QoS in the SUBACK, which may be lower than requested. When the broker forwards a message, it uses the lower of the two values:
effective QoS = min(QoS of the PUBLISH, granted QoS of the subscription)
| Published with | Subscribed with | Delivered to subscriber with |
|---|---|---|
| QoS 2 | QoS 0 | QoS 0 |
| QoS 1 | QoS 2 | QoS 1 |
| QoS 0 | QoS 2 | QoS 0 |
| QoS 2 | QoS 1 | QoS 1 |
The broker never upgrades a message. A message published with QoS 0 always arrives with QoS 0. If you need at-least-once delivery from device to application, both the publisher and the subscriber must use QoS 1 or higher.
mosquitto_sub -h broker.example.com -t 'robot/arm-7/#' -q 1 -v
In MQTT 5.0 the broker can also announce a Maximum QoS in CONNACK. A client must not publish above that level.
QoS and persistent sessions
QoS only protects messages for offline subscribers when it is combined with a persistent session. If a subscriber with a persistent session disconnects, the broker queues QoS 1 and QoS 2 messages that match its subscriptions and sends them when the client reconnects. Queuing QoS 0 messages for offline clients is optional for the broker, so you should not rely on it.
With a clean session, the subscriptions and queued messages are deleted when the client disconnects, and QoS 1 or 2 does not help across that gap. In MQTT 3.1.1 you control this with the Clean Session flag; in MQTT 5.0 with Clean Start and the Session Expiry Interval.
mosquitto_sub -h broker.example.com -i historian-01 -c -q 1 -t 'plant/#'
The -c flag disables clean session, and -i sets a fixed client ID. The broker identifies the session by that client ID, so it must stay the same across reconnects.
How to choose a QoS level
Choose QoS per topic, based on what a lost or duplicated message would cost.
- QoS 0 for high-rate measurements where the next value replaces the last, and for data that is also stored elsewhere.
- QoS 1 for events, alarms and status changes. Make consumers tolerate duplicates.
- QoS 2 for the few messages where a duplicate causes a wrong action and the consumer cannot deduplicate.
Then check the subscribing side. A subscription at QoS 0 silently downgrades every message, whatever the publisher chose.