What is MQTT Last Will and Testament (LWT)? – MQTT Essentials: Part 9

What is MQTT Last Will and Testament (LWT)? – MQTT Essentials: Part 9

author HiveMQ Team

Written by HiveMQ Team

Category: MQTT Essentials MQTT

Published: March 9, 2015

Updated: June 27, 2023

Last Will and Testament (LWT) is a powerful feature in MQTT that allows clients to specify a message that will be automatically published by the broker on their behalf, if or when an unexpected disconnection occurs. It provides a reliable means of communication and ensures that clients can gracefully handle disconnections without leaving topics in an inconsistent state. This feature is particularly valuable when clients must notify others of their unavailability or convey important information upon an unexpected disconnection.

Here’s Part 9 of MQTT Essentials, a ten-part blog series on the core features and concepts of the MQTT protocol, where we we will dive into the concept of Last Will and Testament (LWT) in detail. If you want to understand what are Retained Messages in MQTT?, check out Part 8 of this series. Else, let’s dive in to LWT.

Table of Contents

What is the Purpose of Last Will and Testament (LWT) in MQTT?

Learn about MQTT Protocol

Get the MQTT Essentials eBook

72 pages of MQTT education and learning for beginners and experts alike.

In scenarios where unreliable networks are prevalent, it is common for MQTT clients to experience occasional unintended breaks, which can happen due to loss of connection or depleted batteries. Understanding the type of disconnection (graceful - with a disconnect message, or ungraceful - without a disconnect message) is crucial for taking appropriate actions.

The Last Will and Testament feature in MQTT offers a solution for clients to respond effectively to ungraceful disconnects and ensure proper handling of such events.

The LWT allows clients to notify others about their unexpected disconnections. When a client connects to a broker, it can specify a last-will message. This message follows the structure of a regular MQTT message structure, including a topic, retained message flag, Quality of Service (QoS), and payload. The broker stores this message until it detects an ungraceful disconnect from the client. Upon detecting the disconnection, the broker broadcasts the last will message to all subscribed clients of the corresponding topic. The broker discards the stored LWT message if the client disconnects gracefully using the DISCONNECT message.



By utilizing LWT, you can implement various strategies to handle client disconnections and inform other clients about the offline status.

Core features and concepts of the MQTT protocol, including Last Will and Testament, explained.

How to Configure a Last Will and Testament (LWT) Message for an MQTT Client?

To specify an LWT message for an MQTT client, you include it in the CONNECT message, which is used to initiate the connection between the client and the broker.



For detailed information on establishing the connection between the client and broker, read our article MQTT Client, MQTT Broker, and MQTT Server Connection Establishment Explained.

When does the MQTT Broker Send the LWT Message?

According to the MQTT 3.1.1 specification, the broker sends a client’s Last Will and Testament (LWT) message in the following situations:

  1. I/O error or network failure: If the broker detects any issues with the input/output or network connection, it will distribute the LWT message.
  2. Failed communication within Keep Alive period: If the client fails to communicate with the broker within the specified Keep Alive period, the LWT message is sent. In Part-10 of our MQTT Essentials, we will explore the concept of MQTT Keep Alive time and delve into its significance it.
  3. Client closes connection without DISCONNECT: When the client terminates the network connection without sending a DISCONNECT packet, the broker ensures the LWT message is distributed.
  4. Broker closes connection due to protocol error: If the broker closes the network connection due to a protocol error, it will send the LWT message.

Understanding when and why the broker sends the Last Will and Testament (LWT) messages lays the groundwork for implementing best practices in leveraging this feature, which we will delve into in the next section.

When to Use Last Will and Testament (LWT) in MQTT?

LWT proves invaluable for alerting subscribed clients about an abrupt disconnection of a client. It becomes a powerful tool for storing and communicating client state on specific topics when combined with retained messages.

For instance, by setting a lastWillMessage with Offline payload, enabling the lastWillRetain flag, and specifying the lastWillTopic as client1/status, followed by publishing an Online retained message to the same topic, client1 can keep newly-subscribed clients informed about its online status. Should client1 disconnect unexpectedly, the broker publishes the LWT message with Offline payload as the new retained message, ensuring that clients subscribing to the topic while client1 is offline receive the LWT message and stay up to date on its current status.

LWT not only notifies subscribed clients about unexpected disconnections but also assists in maintaining the system’s integrity by providing valuable information on client states. Combining LWT with retained messages allows you to create a robust solution that stores and communicates the latest client state on specific topics, ensuring reliable updates for all subscribers. This approach enables seamless integration and synchronization between clients, enhancing the overall resilience and functionality of the MQTT network.

The Importance of Last Will and Testament in MQTT: A Summary

To summarize, the Last Will and Testament (LWT) feature in MQTT is crucial in ensuring efficient communication and maintaining system integrity in the event of unexpected client disconnections. By combining LWT with retained messages, developers can store and communicate client state on specific topics, providing valuable information to subscribed clients. LWT empowers MQTT networks with enhanced resilience, seamless integration, and reliable updates, making it a powerful tool for various applications. By understanding the benefits and best practices of LWT, you can leverage this feature to create robust and effective MQTT solutions.

That brings us to the end of Part 9 of our MQTT Essentials series. In the next and the final part of this series, we’ll cover the MQTT heartbeat mechanism and how the broker knows a client is online or offline.

Are you enjoying our content? Then sign up for our newsletter below. If you prefer RSS, you can subscribe to our RSS feed here. Do check out MQTT Glossary to know all the key MQTT terminologies. Watch the video below that complements the concepts discussed in this article.

FAQs on MQTT Last Will and Testament (LWT)

Yes, you can customize the Last Will and Testament (LWT) settings for different MQTT clients or topics. The LWT feature in MQTT allows you to specify a message that will be published by the broker on behalf of a client when the client unexpectedly disconnects from the MQTT network.

Yes, you can combine MQTT Last Will and Testament (LWT) with Quality of Service (QoS) settings. MQTT allows you to specify both the QoS level and the LWT message for a client.

The MQTT Quality of Service (QoS) level of the Last Will and Testament (LWT) message and the QoS level of regular MQTT messages are independent of each other. They can be set and handled differently based on your requirements.

As the new client has connected using the same ClientID, this is treated as a continuation of the previous session (if a persistent session was used), or a new session with the same ClientID (if the previous session was not persistent). As the broker perceives the client as being continuously connected (the old session continuing or a new session starting immediately), it will not publish the LWT message.

MQTT does not directly manage multiple Last Will and Testament (LWT) messages for a client subscribed to various topics. The LWT message is associated with the client's connection rather than specific topics.

If the client's network connectivity is unstable and it repeatedly connects and disconnects, the LWT message could be sent each time the broker detects a disconnection (assuming the client does not properly send a DISCONNECT command each time). When the client reconnects, the LWT message is reset, and the process starts over.

When the client reconnects, it has the option to set a new LWT message. If it does, this new LWT message will replace the previous one. If the client does not set a new LWT message, the previous one is cleared. This means that if the client disconnects unexpectedly again after reconnecting, and it did not set a new LWT message when it reconnected, no LWT message will be sent.

In a high-availability or clustered broker setup, handling of LWT messages would largely depend on the specific implementation of the broker.In some setups, MQTT brokers in a cluster share state information about connected clients, including their LWT messages. If one broker in the cluster detects a client disconnecting unexpectedly, it sends the LWT message on behalf of the client, even if the client was originally connected to a different broker in the cluster.

In some clustered broker setups, the brokers synchronize their state information in real-time or near real-time.

author HiveMQ Team

About HiveMQ Team

We love writing about MQTT, IoT protocols and architecture in general. Our experts are here to help, so reach out to us if we can help!

mail icon Contact HiveMQ
newer posts What Is MQTT Keep Alive and Client Take-Over? – MQTT Essentials Part 10
What are Retained Messages in MQTT? – MQTT Essentials: Part 8 older posts