MQTT is a lightweight messaging protocol commonly used to connect IoT devices with cloud applications. It allows sensors, gateways, embedded systems, and backend services to exchange messages without maintaining a separate connection for every communication request.
MQTT 3.1.1 has been widely used in IoT applications because of its simplicity and low communication overhead. However, as applications become more complex, developers often need better error reporting, message expiration, connection management, and additional message metadata.
MQTT 5 introduces features that help address these requirements. AWS IoT Core supports both MQTT 3.1.1 and MQTT 5, allowing teams to migrate devices gradually instead of upgrading their entire fleet at once.
In this article, you will learn the important differences between MQTT 3.1.1 and MQTT 5, understand the AWS IoT Core compatibility considerations, and follow a practical migration strategy.
What Is the Difference Between MQTT 3.1.1 and MQTT 5?
MQTT 3.1.1 provides the core messaging capabilities required by most IoT applications, including publishing, subscribing, quality of service, and persistent sessions.
MQTT 5 retains these fundamental capabilities while adding features that give applications more control over messaging behavior.
The following table summarizes the major differences.
Feature | MQTT 3.1.1 | MQTT 5 |
|---|
Error reporting | Limited connection and operation feedback | More detailed reason codes |
Message expiration | No standard message-expiry property | Supports message expiration |
Session expiration | Session persistence is controlled through connection settings | Supports a configurable session-expiry interval |
Message metadata | Limited protocol-level metadata | Supports user properties |
Request-response messaging | Usually implemented through application conventions | Supports response topics and correlation data |
Connection configuration | Fewer configurable properties | Additional connection properties and negotiated settings |
Subscription behavior | Basic subscription options | Adds subscription options such as subscription identifiers and shared-subscription-related capabilities |
Server redirection | Not available as an MQTT 3.1.1 feature | Defines server redirection mechanisms, subject to broker support |
Although MQTT 5 offers additional capabilities, not every broker supports every feature defined by the protocol. AWS IoT Core has its own implementation limits that must be considered before migration.
Important MQTT 5 Features in AWS IoT Core
Improved Error Reporting
In MQTT 3.1.1, an application may receive limited information when a connection or subscription fails. This can make troubleshooting difficult, particularly when many devices connect to the same cloud service.
MQTT 5 introduces reason codes that provide more information about connection failures and messaging operations.
For example, an application can distinguish between a successful subscription and a subscription that was rejected because of permissions or other restrictions.
This helps developers improve logging and implement more useful recovery strategies.
However, applications should not assume that every failure requires a retry. Authentication failures, invalid topic filters, and authorization problems generally require configuration changes rather than repeated connection attempts.
Message Expiration
MQTT 5 allows publishers to specify how long a message remains valid.
Consider a temperature monitoring system that sends readings to a cloud application. A reading that arrives several hours late may no longer be useful for a real-time dashboard.
A publisher can assign a message-expiry interval so that the broker does not deliver the message after its validity period has elapsed.
This is useful for temporary sensor readings, time-sensitive status updates, and messages that become irrelevant after a specific period.
Message expiration does not replace application-level timestamps. If a consumer needs to determine when a measurement was originally recorded, include that timestamp in the message payload.
Session Expiration
MQTT 3.1.1 uses the Clean Session setting to control whether session state is maintained across connections.
MQTT 5 introduces the Session Expiry Interval, which allows clients to specify how long the broker should retain session state after a connection ends.
For example, a device that frequently loses network connectivity may benefit from retaining its subscriptions and eligible queued messages during a temporary interruption.
A longer session expiry interval can improve recovery behavior, but it also requires consideration of storage, message volume, and device reconnection patterns.
For AWS IoT Core, verify the supported session behavior and applicable service limits before choosing an interval.
User Properties and Request-Response Messaging
MQTT 5 introduces user properties, which allow publishers to attach additional key-value metadata to messages.
For example, a message might include an application identifier or a processing category.
Request-response messaging also becomes easier to represent through response topics and correlation data.
These features can reduce the need to invent custom conventions for every application. However, they do not replace authorization checks or application-level validation.
AWS IoT Core supports a defined subset of MQTT 5 functionality, so confirm which properties are available for your intended messaging pattern.
What Changes When Migrating an Existing MQTT Client?
Moving from MQTT 3.1.1 to MQTT 5 involves more than changing a protocol-version setting.
The client library, connection configuration, error-handling logic, and application behavior may all need updates.
Client Library Compatibility
Start by checking whether your existing MQTT client supports MQTT 5 and AWS IoT Core's authentication methods.
For example, a device that currently uses X.509 certificates over mutual TLS must continue to establish a secure connection using the supported endpoint and authentication configuration.
Some client libraries implement MQTT 3.1.1 and MQTT 5 through different APIs. Connection callbacks, publishing methods, subscription acknowledgments, and shutdown behavior may therefore require changes.
Do not assume that an existing MQTT 3.1.1 client can use MQTT 5 simply by changing a configuration value.
Connection and Session Configuration
Review the connection settings before deploying the new client.
Pay particular attention to:
Client identifiers and their uniqueness.
Clean Start and Session Expiry Interval.
Keep-alive settings.
Reconnection behavior.
Authentication and authorization.
Will messages and their associated properties.
For persistent sessions, verify that the application handles reconnecting clients and previously established subscriptions correctly.
A change in session configuration can affect how messages are queued and delivered after a device disconnects.
Publishing and Subscribing
Review every publish and subscribe operation for assumptions about acknowledgment behavior.
For example, an application may currently treat a successful method call as proof that a message was accepted by the broker. Depending on the client API, that assumption may be incorrect.
With MQTT 5, clients can receive acknowledgment packets containing reason codes. Applications should inspect those responses when the selected client library exposes them.
AWS IoT Core supports QoS 0 and QoS 1, but not QoS 2. Do not configure QoS 2 as part of the migration and expect it to work.
Practical Example: Publishing an MQTT 5 Message
The following example illustrates the structure of an MQTT 5 publish operation using JavaScript and the mqtt client library.
It assumes that the client has already connected successfully to an MQTT 5-compatible endpoint and that the connection uses an authentication method accepted by AWS IoT Core.
const mqtt = require("mqtt");
const client = mqtt.connect("mqtts://your-iot-endpoint:8883", {
protocolVersion: 5,
clientId: "temperature-sensor-001",
// Configure valid TLS credentials and other
// connection options for your environment.
});
client.on("connect", () => {
const message = JSON.stringify({
deviceId: "temperature-sensor-001",
temperature: 26.4,
recordedAt: new Date().toISOString()
});
client.publish(
"sensors/temperature",
message,
{
qos: 1,
properties: {
messageExpiryInterval: 60,
userProperties: {
source: "temperature-sensor"
}
}
},
(error) => {
if (error) {
console.error("Publish failed:", error.message);
return;
}
console.log("Publish operation completed.");
}
);
});
client.on("error", (error) => {
console.error("MQTT connection error:", error.message);
});
This example demonstrates MQTT 5 message properties, but it is not a complete production connection setup. In particular, the endpoint, certificate configuration, and authentication settings must match the selected AWS IoT Core connection method.
The message-expiry property limits the message's useful lifetime, while the user property carries additional metadata. QoS 1 requests at-least-once delivery, which means the application must be prepared for duplicate messages.
The publish callback should not be interpreted as proof that a downstream application has processed the message. For workflows that require confirmation of business processing, implement an application-level acknowledgment.
Also verify the exact client-library API and AWS IoT Core feature support before using optional properties in a production deployment.
AWS IoT Core Compatibility Considerations
MQTT 5 defines features that are not necessarily available in every broker implementation. AWS IoT Core supports MQTT 5 with documented differences from the full protocol specification.
Important considerations include:
Capability | Migration consideration |
|---|
QoS 0 and QoS 1 | Supported; QoS 2 is not supported |
Message expiry | Check the applicable service behavior and limits |
Session expiry | Verify the supported session configuration and limits |
Reason codes | Use available responses to improve error handling |
User properties | Confirm support for the intended publishing workflow |
Server redirection | Do not assume MQTT 5 server redirection is supported |
Authentication | Continue using a supported AWS IoT Core authentication method |
Authorization | Ensure IoT policies permit the required connection, publish, and subscribe operations |
One particularly important limitation is that AWS IoT Core does not support the MQTT 5 AUTH packet. Applications must use an authentication method supported by the service rather than relying on that packet.
Before migration, review the service's supported MQTT 5 properties and protocol differences. A feature defined in the MQTT standard should not be treated as automatically available in AWS IoT Core.
Best Practices for a Safe Migration
Migrate a Small Group of Devices First
Begin with a development environment or a small group of noncritical devices.
Test connection establishment, publishing, subscribing, disconnection, reconnection, and session recovery before expanding the rollout.
A limited rollout helps identify differences in client behavior without affecting the entire device fleet.
Preserve Backward Compatibility
During a gradual migration, MQTT 3.1.1 and MQTT 5 clients may operate at the same time.
Keep topic names and message payloads compatible where possible. If MQTT 5 properties introduce new behavior, ensure that existing consumers do not depend on metadata they cannot access.
Protocol compatibility does not automatically guarantee application compatibility.
Monitor Connection and Messaging Errors
Record connection failures, disconnections, subscription failures, publish errors, and acknowledgment reason codes when available.
Monitoring should distinguish between temporary network failures and permanent configuration problems.
Use bounded exponential backoff with jitter for retryable failures. This prevents large numbers of devices from reconnecting simultaneously after a network outage.
Test Duplicate and Delayed Messages
QoS 1 can result in duplicate delivery, so consumers should be designed to handle repeated messages safely.
For business operations, use stable message identifiers or idempotency keys when duplicate processing could cause incorrect results.
Test message expiration and session recovery separately because they address different behaviors.
Keep Credentials and Policies Secure
Use appropriate certificate or credential management, least-privilege IoT policies, and secure transport.
Do not place private keys, passwords, or long-lived credentials directly in source code.
Validate permissions for the exact topics that devices need to publish to or subscribe to.
Common Migration Problems and Troubleshooting
Problem | Possible cause | Recommended action |
|---|
Connection fails | Invalid endpoint, TLS configuration, or authentication | Verify endpoint, certificates, and authentication settings |
Subscription is rejected | IoT policy does not permit the topic | Review the policy and topic filter |
Messages arrive more than once | QoS 1 delivery behavior | Make message processing idempotent |
Session state is missing | Incorrect session settings or expired session | Review Clean Start and Session Expiry Interval |
Messages arrive too late | Offline queues or application processing delays | Review expiry settings and consumer processing |
MQTT 5 property has no expected effect | Unsupported service behavior or incorrect client configuration | Check client documentation and AWS IoT Core limitations |
Reconnection attempts continue failing | Permanent authorization or configuration error | Inspect failure details before retrying indefinitely |
Troubleshooting should start with the client logs and connection events. Then verify AWS IoT Core authorization, client settings, and the exact MQTT 5 properties involved in the failed operation.
Advantages and Disadvantages of MQTT 5 Migration
MQTT 5 provides several advantages for applications that need better control over messaging behavior.
It offers more detailed error reporting, configurable message and session expiration, additional message metadata, and improved support for request-response patterns. These capabilities can simplify application design and make failures easier to diagnose.
However, migration also introduces costs. Client APIs may change, older devices may require separate implementations, and some protocol features may not be supported by AWS IoT Core. Teams must also test reconnection behavior, session persistence, message duplication, and backward compatibility.
For simple IoT applications that already meet their requirements with MQTT 3.1.1, migration may not provide enough value to justify the changes immediately.
Summary
Migrating from MQTT 3.1.1 to MQTT 5 can improve how an IoT application handles errors, message expiration, session persistence, and application metadata.
However, the migration should begin with a review of client-library support and AWS IoT Core's implementation limits. Developers should test connection behavior, authorization, publishing, subscriptions, reconnection, and duplicate-message handling before rolling out the new client across a device fleet.
The most reliable approach is to migrate gradually, preserve compatibility between old and new clients, and monitor the system throughout the rollout. MQTT 5 provides additional capabilities, but those capabilities deliver value only when the application and broker are configured to use them correctly.
Join the conversation! Your thoughts help the community grow.