MQTT QoS: what levels 0, 1 and 2 guarantee and what they cost

Catalin NegruPublished 6 min read

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 0QoS 1QoS 2
GuaranteeAt most onceAt least onceExactly once
Packets per message124
ExchangePUBLISHPUBLISH, PUBACKPUBLISH, PUBREC, PUBREL, PUBCOMP
Packet identifierNoneYesYes
Can be lostYesNoNo
Can be duplicatedNoYesNo
Sender stores the messageNoUntil PUBACKUntil PUBREC
Queued for an offline sessionNot requiredYesYes

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 10

If 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 atSubscription grantedDelivered at
222
211
121
100
020

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:

  1. The client connects with a persistent session: clean session 0 in MQTT 3.1.1, or a Session Expiry Interval above zero in MQTT 5.0.
  2. It reconnects with the same client identifier.
  3. Its subscription was granted QoS 1 or 2.
  4. 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

DataSuggested levelReason
Frequent telemetry where the next sample replaces the last0A lost sample is corrected seconds later, and overhead is lowest
Readings that must reach a historian, alarms, events1No loss; duplicates are handled by the consumer
Commands that must not run twice, billing counts2, or 1 with an idempotent designDuplicates 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.