Understanding MQTT QOS Levels- Part 1

mqtt-qosMQTT provides 3 QOS levels-

  • QOS 0 – Once (not guaranteed)
  • QOS 1 – At Least Once (guaranteed)
  • QOS 2 – Only Once (guaranteed)

The QOS levels are a way of guaranteeing message delivery and they  refer to the connection between a broker and a client.

In this two part tutorial we will look in detail at the message flow when publishing using all three QOS levels.

We also look at the advantages and disadvantages of using the various levels

QOS 0 –  Once

This is the fastest method and requires only 1 message. It is also the most unreliable transfer mode.

The message is not stored on the sender, and is not acknowledged.

The message will be delivered only once, or not at all.

Once the message has been sent by the client it is deleted from the outbound message queue.

Therefore with this QOS level there is no possibility of duplicate messages.

QOS 1 – At Least Once

Click To Enlarge

This level guarantees that the message will be delivered at least once, but may be delivered more than once. (See Flow Diagram on right.)

Publishing with QOS of 1 requires 2 messages.

The sender sends a message and waits for an acknowledgement (PUBACK).

If it receives an acknowledgement then it notifies the client app, and deletes the message from the outbound queue..

If it doesn’t receive an acknowledgement it will resend the message with the DUP flag set (Duplicate Flag).

The message will continue to be resent at regular intervals, until the sender receives an acknowledgement.

If the message is being sent to the broker then the broker will forward that message to subscribers even though the duplicate flag is set.

Therefore subscribers can receive the same message multiple times.

QOS 1 Example


For this example I have created a Python script to publish messages with a QOS of 1.

I have also hacked the Python Client Class so that I can suppress reception of the PUBACK message to simulate a network failure.

In addition I have a monitor subscribed to the topics that I’m publishing on, so I can see all published messages.

The example tries to illustrate:

  • Message Flow for QOS 0 and QOS 1 Messages
  • Normal QOS level 0 publish
  • Normal QOS 1 publish and message deletion
  • How Unacknowledged messages are handled
  • Message re-sending on failure
  • Duplicate Flag usage
  • Message storage on Client in case of disconnection
  • Duplicate messages with QOS level 1

Step 1

To start we do a simple publish with QOS=1 and observe the PUBACK being received, the message being marked as delivered, and removed from the outbound message queue.

Then we simulate a network problem by blocking PUBACK message. Now you should notice that the message remains stuck in the outbound message queue.


Step 2

Now we publish two more messages the first with QOS of 0. This message doesn’t have a PUBACK and is removed from the message queue once sent.

The second message is sent with a QOS of 1 and remains stuck in the outbound queue even though it has been sent .


Step 3

Now the client attempts to resend the message held in the queue (MID=2). Notice the Duplicate flag is now set.


Step 4

Now will simulate a dropped connection by doing a disconnect and reconnect. You can see that the messages (m2 and m4) are still in the queue, and the client re-sends the messages with the duplicate flag set.


Step 5

Now we change the setting to let the PUBACK messages come through.


Step 6

After a short time the client republishes the messages again, but this time the PUBACK  is received OK, and the messages finally get removed from the outbound queue.


Step 7

Here is what is seen on the monitor notice the duplicate messages.


Important Note: Resending a message depends on the client and broker.

Mosquitto will not currently resend the message to a client if it doesn’t get a PUBACK.

If the client subscribed with a clean session of False the if the client disconnects and reconnects it will receive the message as it is held in the queue as it wasn’t acknowledged.

This is what the specification says:

4.4 Message delivery retry 1315

When a Client reconnects with CleanSession set to 0, both the Client and Server MUST re-send any unacknowledged PUBLISH Packets (where QoS > 0) and PUBREL Packets using their original Packet Identifiers [MQTT-4.4.0-1]. This is the only circumstance where a Client or Server is REQUIRED to  redeliver messages.

In Part 2 we look in detail at publishing using QOS 2.

Was This Useful?

Related Tutorials and Resources:

Please rate? And use Comments to let me know more


    1. It is client dependent. the python client is set to 20 secs.
      self._keepalive = 60
      self._message_retry = 20


      1. I have the same question about how long will the publisher resend the missing message at qos 1, but my question is for the client of mosquitto, which written in C language.
        I found that before mosquitto version 1.5, it used “retry_interval” to control, but now it seem to take that parameter away.

        1. Sorry I don’t know as I don’t really use that client. However i had a similar problem with the broker sending to a client and discovered that retries are not required except on reconnect.
          This is what the docs say https://www.eclipse.org/paho/files/mqttdoc/MQTTClient/html/struct_m_q_t_t_client__connect_options.html

          The time interval in seconds after which unacknowledged publish requests are retried during a TCP session. With MQTT 3.1.1 and later, retries are not required except on reconnect. 0 turns off in-session retries, and is the recommended setting. Adding retries to an already overloaded network only exacerbates the problem.

          So I guess the most likely answer is they are not retried unless you disconnect and reconnect.

  1. Sir,
    I configured my mosquitto broker, it works well for clients with Qos 0. but, when client configured for Qos 1 and 2 , I am not able to receive subscribe message. I have kept Clean session Flag to False and also my Keep alive time is 120 sec, 500sec.
    My clients gets disconnected from Mqtt broker if it not able to send acknowledge for publish message.
    can you please help me with my mosquitto configuration, I check it with clients using MQTTbox and MQTTLens.

  2. Hi Steve,
    Thanks for this article ! I am pretty new to this, so this helps a lot. Actually I want to implement feature to forward data from application (mqtt client) to cloud. Is there any tool or libraries to achieve mqtt client connection retries with cloud if connection lost or any other failure. Your suggestion will be more helpful to proceed further in my project implementation.

    Thanks in advance.

      1. Hi Steve,
        How can we achieve auto reconnect using paho mqtt client in python and C++. Could you please explain in detail?

  3. Hi Steve, thanks for this article ! I am pretty new to this, so this helps a lot.

    It is not clear to me if I have to write code to handle proper message flow at QoS = 1 as decribed in your example. Otherwise stated: when I publish with QoS = 1 does the client itself ensure that the message is properly sent in case of a network glitch? Or should I write code that collects PUBACK and act accordingly?

    I would expect that a smart client handles this without the user having to act.

    The answer is probably in the python scripts that you recoomend over here. But it is hard to read for me.


    1. The PUBACK for QOS=1 and the other messages related to QOS=2 are done by the client and so you don’t need to worry about writing code to do this.
      However you need to be aware of them as you can use the puback which generates a callback for controlling message flow. i.e wait for an ack before sending next message.
      You also need to be aware that extra messages are generated which may or may not be a problem and the qos of 1 can result in duplicate messages so you may need to write code to take care of that.
      Hope that makes more sense

  4. Hi

    Please how can you deal with duplicate messages in Paho, is there a way to identify duplicates in a qos 1 situation?


    1. Hi
      in the on_message callback I think you can access it using message.dup
      the call doesn’t cause an error but I have tried it with duplicates to test that it is set.

  5. This article is excellent. Your website is the best resource I’ve found for quickly learning about Paho MQTT with Python. The only thing that would possibly make it better, is if you included your code via GitHub or something. Thanks a lot!

  6. Hey,
    first of all, nice tutorial. Clear and concise explanation
    I have a doubt, who actually publishes the PUBACK? Is it being done by the client who has subscribed or by the broker, who knows that the message is actually delivered to the client?

    Dhaval Shah

  7. Thank you for the helpful information.

    For my application which includes a database I was interested in reliable delivery. In my searches I’ve found this is rarely addressed. My conclusions are that it is not possible with commonly used software. paho mqtt provides no way for the app to acknowledge receipt of a message so presumably the message is lost if the power goes out between when paho acks the message and when the app commits it to persistent storage. In addition, the mosquitto broker writes persistent info to disk based on a timer so there is a 30 minute (changable) window when a power failure will cause loss of all acknowledged but undelivered messages.

    1. Hey, can u suggest me any simple example for connecting esp32 with labview trought mqtt broker.?

    1. Hi
      You can’t configure QOS on Mosquitto. QOS is done on the client publish and subscribe.
      The only time you configure QOS on Mosquitto is when it is used as a bridge and in this case Mosquitto functions like a client.

  8. Why there is a need of QoS when TCP/IP gives guaranteed delivery mechanism already? All retry, failure, duplicate is taken care by TCP itself.

Leave a Reply

Your email address will not be published. Required fields are marked *