MQTT QoS: what levels 0, 1 and 2 guarantee and what they cost
Part of the MQTT guide
MQTT QoS (quality of service) is a two-bit field in each PUBLISH packet that sets the delivery guarantee for that message between a client and the broker. QoS 0 delivers at most once with no acknowledgement, QoS 1 delivers at least once and may duplicate, and QoS 2 delivers exactly once using a four-packet exchange. The level applies to one hop at a time, so a message is covered twice: from the publisher to the broker, and from the broker to each subscriber.
This page is part of the MQTT guide. The fixed header that carries the QoS bits is decoded in What is MQTT?.
The three MQTT QoS levels at a glance
| QoS 0 | QoS 1 | QoS 2 | |
|---|---|---|---|
| Guarantee | At most once | At least once | Exactly once |
| Packets per message | 1 | 2 | 4 |
| Exchange | PUBLISH | PUBLISH, PUBACK | PUBLISH, PUBREC, PUBREL, PUBCOMP |
| Packet identifier | None | Yes | Yes |
| Can be lost | Yes | No | No |
| Can be duplicated | No | Yes | No |
| Sender stores the message | No | Until PUBACK | Until PUBREC |
| Queued for an offline session | Not required | Yes | Yes |
The QoS bits are bits 2 and 1 of the first byte of PUBLISH. Bit 3 is DUP and bit 0 is RETAIN, so the first byte reads 30 for QoS 0, 32 for QoS 1 and 34 for QoS 2 when neither flag is set. The value 3 is not allowed, and a receiver that sees it closes the connection.
QoS 0: at most once
The sender writes the PUBLISH to the TCP connection and forgets it. There is no acknowledgement and no retry at the MQTT level. TCP still retransmits lost segments, so on a connection that stays up a QoS 0 message normally arrives. It is lost when the connection breaks with the message still in a buffer, or when the receiver is overloaded and drops it.
QoS 1: at least once
The sender keeps the message until the receiver acknowledges it with a PUBACK that carries the same packet identifier. Here the text 42.7 is published to site1/pump3/flow with packet identifier 10, using MQTT 3.1.1:
PUBLISH: 32 18 00 10 73 69 74 65 31 2F 70 75 6D 70 33 2F 66 6C 6F 77 00 0A 34 32 2E 37
32 packet type 3 (PUBLISH), DUP 0, QoS 1, RETAIN 0
18 remaining length: 24 bytes follow
00 10 topic length: 16 bytes
73 ... 77 "site1/pump3/flow"
00 0A packet identifier 10
34 32 2E 37 payload "42.7"PUBACK: 40 02 00 0A
40 packet type 4 (PUBACK)
02 remaining length
00 0A packet identifier 10If the connection drops before the PUBACK arrives, the sender cannot tell whether the PUBLISH was lost or only the acknowledgement was. When the session resumes it sends the message again with the DUP flag set (first byte 3A). If the first copy did arrive, the receiver now has two. That is the meaning of at least once.
QoS 2: exactly once
QoS 2 adds a second round so that both sides agree the message has been handed over once.
Sender Receiver
| PUBLISH (id 10) 34 ... |
|------------------------------->| stores the identifier, delivers the message
| PUBREC 50 02 00 0A |
|<-------------------------------|
| PUBREL 62 02 00 0A | sender may now discard the message
|------------------------------->|
| PUBCOMP 70 02 00 0A | receiver discards the identifier
|<-------------------------------|Until it receives PUBREL, the receiver treats any PUBLISH with identifier 10 as a repeat and does not deliver it again. After PUBCOMP, both sides release the identifier. The cost is four packets and state held on both ends for every message in flight.
Packet identifiers, DUP and retransmission
The packet identifier is a 16-bit number from 1 to 65,535, chosen by the sender and unique among its unacknowledged packets in that direction. It is reused once the exchange completes. It is not a sequence number and says nothing about order across messages.
The DUP flag means this PUBLISH may be a retransmission of an earlier attempt. It is set by the sender on that hop only; the broker does not copy it to subscribers.
The two versions differ on when a retransmission happens. MQTT 5.0 allows unacknowledged messages to be resent only when a client reconnects to an existing session, never on a timer while the connection is up, because TCP already handles loss on a live connection. MQTT 3.1.1 requires the resend on reconnect, and some 3.1.1 clients also retry on a timer.
QoS is per hop, and the broker can downgrade it
The publisher sets the QoS of the message it sends to the broker. Each subscriber sets a maximum QoS in its subscription, and the broker replies with the level it granted. The broker then forwards each message at the lower of the two:
| Published at | Subscription granted | Delivered at |
|---|---|---|
| 2 | 2 | 2 |
| 2 | 1 | 1 |
| 1 | 2 | 1 |
| 1 | 0 | 0 |
| 0 | 2 | 0 |
Two consequences follow. A publisher that sends at QoS 1 and gets its PUBACK knows the broker has the message, and nothing more; whether any subscriber received it is a separate exchange. And an exactly-once publisher feeding a QoS 0 subscription gives an at-most-once result.
A broker may also refuse the higher levels. In MQTT 5.0 it states its limit in the Maximum QoS property of CONNACK.
What it takes to receive messages sent while offline
All of the following have to be true for a broker to hold messages for a disconnected client:
- The client connects with a persistent session: clean session
0in MQTT 3.1.1, or a Session Expiry Interval above zero in MQTT 5.0. - It reconnects with the same client identifier.
- Its subscription was granted QoS 1 or 2.
- The messages were published at QoS 1 or 2.
Miss one and the messages are gone. The first is the common miss, because many client libraries default to a clean session. Brokers also cap the queue per session, and MQTT 5.0 publishers can set a Message Expiry Interval so that stale readings are dropped instead of delivered hours later.
Which QoS level to use
| Data | Suggested level | Reason |
|---|---|---|
| Frequent telemetry where the next sample replaces the last | 0 | A lost sample is corrected seconds later, and overhead is lowest |
| Readings that must reach a historian, alarms, events | 1 | No loss; duplicates are handled by the consumer |
| Commands that must not run twice, billing counts | 2, or 1 with an idempotent design | Duplicates cause harm |
In practice QoS 1 with duplicate-tolerant consumers covers most industrial data. A reading that carries its own timestamp is idempotent: storing the same value for the same instant twice changes nothing. A command such as “set the valve to 40 percent” is idempotent; “open 5 percent more” is not, and should be redesigned before reaching for QoS 2.
QoS does not replace a buffer in the device. If the publisher’s process restarts, or the device loses power while disconnected, any unacknowledged messages held in memory are lost at every level. Data that matters is written to local storage with its timestamp and sent when the connection returns.
Check also that the client library reports QoS 1 failures. Publishing at QoS 1 and never checking for the acknowledgement gives QoS 0 behaviour with more traffic.
QoS with ControlCom
The ControlCom Connect documentation states that the platform’s MQTT broker supports QoS levels 0, 1 and 2, along with Last Will messages and configurable keep alive intervals. Its guidance for device clients is to set the QoS level by the importance of the data, consider persistent sessions for devices that connect intermittently, and buffer data locally when the connection is lost. Each reading in the JSON payload can carry its own timestamp in Unix milliseconds, so buffered readings sent late are stored at the time they were measured.
The MQTT documentation covers the payload and connection practices, and the platform overview shows where the data goes afterwards. For how topic filters interact with the granted level, see MQTT topics and wildcards.
Publish timestamped readings to ControlCom Connect at the QoS level the data calls for, and send buffered values after an outage with their original timestamps.