learn/mqtt

MQTT QoS levels explained: 0, 1 and 2

Short answer

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.

Updated:

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.

01ultramq/learn/faq

Frequently asked questions

What is the default QoS in MQTT?

The protocol has no global default; QoS is set on each PUBLISH and each subscription. Most client libraries and the mosquitto_pub and mosquitto_sub tools use QoS 0 unless you choose another level.

Can MQTT QoS 1 deliver a message twice?

Yes. If the PUBACK is lost, the sender resends the message with the DUP flag set, and the receiver may process it twice. Applications using QoS 1 should handle duplicates.

Does QoS 2 guarantee end-to-end delivery from publisher to subscriber?

QoS 2 guarantees exactly-once delivery on each hop: publisher to broker and broker to subscriber. The subscriber only gets QoS 2 if its subscription also requested QoS 2.

Which MQTT QoS level should I use for sensor data?

For frequent sensor readings where the next value replaces the last, QoS 0 is usually enough. Use QoS 1 when every message matters and duplicates are harmless or can be filtered.

03ultramq/start

Talk to an engineer about your project.

Tell us what you want to connect, where it has to run and what the data should feed. We reply by email.

SUBultramq/#