MQTT Reason Code Introduction and Quick Reference
EMQX TeamJun 19, 2023
Reason Code
The primary purpose of Reason Code in MQTT is to provide more detailed feedback to the client and server. For example, we can feed back the Reason Code corresponding to the wrong username or password to the client in the CONNACK packet, so that the client can know why it cannot connect.
Reason Code in MQTT 3.1.1
Although MQTT 3.1.1 already supports Reason Code, it doesn't define many available Reason Codes. In fact, they are very limited.
Among the two MQTT packets that support Reason Code, the CONNACK packet has only 5 Reason Codes to indicate failures. And the SUBACK packet has only one Reason Code for indicating failure, it cannot even provide further details about the reason for the subscription failure. Moreover, for operations such as publishing and unsubscribing that don't support Reason Code, we can't even determine whether the operation was successful or not. This makes development debugging unfriendly and hinders the implementation of robust code.
Reason Code in MQTT 5.0
So In MQTT 5.0, the number of available Reason Codes has been expanded to 43, and it is specified that Reason Codes below 0x80 are used to indicate success, while Reason Codes greater than or equal to 0x80 are used to indicate failure. Unlike MQTT 3.1.1, where Reason Codes below 0x80 could also indicate failure. This allows clients to determine whether an operation was successful or not quickly.
Furthermore, MQTT 5.0 extends the support for Reason Codes to the following packets: CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT, and AUTH. Now, we can not only determine if a message publication was successful but also understand the reasons for failure, such as the absence of matching subscribers or insufficient privileges to publish to a specific topic.
Most MQTT packets include only a single Reason Code, except for SUBACK and UNSUBACK. This is because the SUBSCRIBE and UNSUBSCRIBE packets can contain multiple topic filters, and each topic filter must have a corresponding Reason Code to indicate the result of the operation. Therefore, SUBACK and UNSUBACK packets need to accommodate multiple Reason Codes. That's why Reason Codes in other packets are located in the Variable Header, while the Reason Codes in SUBACK and UNSUBACK are located in the Payload.
In this article's final Reason Code quick reference table, we have provided detailed explanations and use cases for each Reason Code in MQTT 5.0. You can take a look at it for more information.
Indicates to the client why the connection was disconnected
In MQTT 3.1 and 3.1.1, the DISCONNECT packet could only be sent by the client. Therefore, when a client violated certain restrictions, the server could only directly close the network connection without providing additional information to the client. This made it challenging to investigate the reason for the disconnection.
Now in MQTT 5.0, the server can send a DISCONNECT packet to the client before closing the network connection. The client can use the Reason Code in the DISCONNECT packet to get why the connection was disconnected, such as the packet being too large, the server being busy, and so on.
Reason String
Reason String is a complement to Reason Code in MQTT 5.0, providing a human-readable string designed for diagnostic purposes. While Reason Code can indicate most error reasons, developers or operators may still need more intuitive contextual information.
For example, when the server indicates an invalid topic filter to the client using the Reason Code (0x8F), developers still have no specific information about the reason. Is it due to exceeding the maximum number of topic levels or including characters not accepted by the server? However, if the server can return a Reason String similar to "The number of topic levels exceeds the limit, the maximum is 10," developers can quickly understand the reason and make adjustments.
In practical use, the content of the Reason String depends on the specific implementation of the client and server. Therefore, a correctly implemented receiving end should not attempt to parse the content of the Reason String. Recommended usage includes but is not limited to using the Reason String when throwing exceptions or writing it to logs.
Finally, Reason String is an optional feature, and whether a Reason String is received depends on whether the peer supports it.
MQTT 5.0 Reason Code Quick Reference Table
| Reason Code | Name | Packets | Details |
|---|---|---|---|
| 0x00 | Success | CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, UNSUBACK, AUTH | This Reason Code can be used in all packets with Reason Code, such as CONNACK, DISCONNECT packet, etc. It is usually used to indicate success, such as successfully connected, successfully unsubscribed, successfully received packets, successfully authenticated, and so on. |
| 0x00 | Normal disconnection | DISCONNECT | In the DISCONNECT packet, a Reason Code of 0 indicates a regular disconnection, where the Will Message will not be published. |
| 0x00 | Granted QoS 0 | SUBACK | 0, 1, and 2 in the SUBACK packet are used to indicate the subscription result. They all represent a successful subscription, and at the same time, they indicate the maximum QoS level granted to the subscriber. 0, 1, and 2 exactly correspond to three QoS levels.This is because the maximum QoS level granted by the server may be smaller than the maximum QoS level requested when subscribing. For example, if the maximum QoS level requested during subscription is 2, but the server only supports QoS 1, etc. |
| 0x01 | Granted QoS 1 | SUBACK | - |
| 0x02 | Granted QoS 2 | SUBACK | - |
| 0x04 | Disconnect with Will Message | DISCONNECT | Only used for DISCONNECT packets, and it is suitable for situations where the client wants to disconnect normally, but the server still needs to publish a will message. For example, the clients want to be notified of session expiration. |
| 0x10 | No matching subscribers | PUBACK, PUBREC | This reason Code is used to indicate to the sender that the message has been received, but there is currently no matching subscriber, so only the server can use this Reason Code.We can know that no one will receive our message by receiving a response packet with a Reason Code of 0x10, but we cannot assume that everyone will receive our message by not receiving a response message with Reason Code 0x10, unless there will be at most one subscriber.But it should be noted that using 0x10 instead of 0x00 when there is no matching subscriber is not a mandatory behavior, it depends on the specific implementation of the server. |
| 0x11 | No subscription existed | UNSUBACK | Only used for UNSUBACK packets, indicating that no matching subscription was found when unsubscribing. |
| 0x18 | Continue authentication | AUTH | Only used for AUTH packets, which means continuing authentication. Through this Reason Code, any number of AUTH packets can be exchanged between the client and the server to meet the needs of different authentication methods. |
| 0x19 | Re-authenticate | AUTH | Only used for AUTH packets. After the enhanced authentication is successful, the client can initiate re-authentication at any time by sending an AUTH packet with Reason Code 0x19. During re-authentication, the sending and receiving of other packets will continue normally. If re-authentication fails, the connection will be closed. |
| 0x80 | Unspecified error | CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT | Indicates an unspecified error. When one party does not wish to disclose the specific cause of the error to the other party, or no Reason Code can match the current situation in the protocol specification, it can use this Reason Code in the packet. |
| 0x81 | Malformed Packet | CONNACK, DISCONNECT | When receiving a control packet that cannot be correctly parsed according to the protocol specification, the receiver must send a DISCONNECT packet with Reason Code 0x81 to disconnect. If there is a problem with the CONNECT packet, the server should use the CONNACK packet.When the reserved bit in the fixed header is not set to 0 according to the protocol requirements, the QoS is specified as 3, and the UTF-8 string contains a null character in the control packet, it will be considered a malformed packet. |
| 0x82 | Protocol Error | CONNACK, DISCONNECT | Errors detected after the control packet is parsed according to the protocol specification, such as data not allowed by the protocol, behavior inconsistent with the protocol requirements, etc., will be considered protocol errors.The receiver must send a DISCONNECT packet with Reason Code 0x81 to disconnect. If there is a problem with the CONNECT packet, the server should use the CONNACK packet.Common protocol errors include the client sending two CONNECT packets within one connection, one packet containing multiple identical properties, a property being set to a value not allowed by the protocol, etc.But when we have other more specific Reason Codes, we will not use 0x81 (Malformed Packet) or 0x82 (Protocol Error).For example, the server has declared that it does not support retained messages, but the client still sends retained messages to the server, which is essentially a protocol error, but we will choose to use 0x9A (Retain not supported), which can more clearly indicate the cause of the error. |
| 0x83 | Implementation specific error | CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT | The packet is valid, but not accepted by the current receiver's implementation. |
| 0x84 | Unsupported Protocol Version | CONNACK | Only used for CONNACK packets. For the server that supports MQTT 5.0, if the MQTT protocol version currently used by the client is not supported, or the client specifies a wrong protocol version or protocol name. For example, suppose the client sets the protocol version to 6. In that case, the server can send a CONNACK packet with Reason Code 0x84, indicate that the protocol version is not supported and its identity as an MQTT broker, and then close the network connection.Of course, the server can also choose to close the network connection directly, because the MQTT client using MQTT 3.1 or 3.1.1 may not understand the meaning of the Reason Code 0x84. Both versions use 0x01 in the CONNACK packet to indicate that the protocol version specified by the client is not supported. |
| 0x85 | Client Identifier not valid | CONNACK | Only used for CONNACK packets, indicating that the Client ID is a valid string, but the server does not allow it. Possible situations are that the Clean Start is 0, but the Client ID is empty, or the Client ID exceeds the maximum length allowed by the server, and so on. |
| 0x86 | Bad User Name or Password | CONNACK | Only used for CONNACK packets, indicating that the client has used the wrong username or password, which means the client will be refused to connect. |
| 0x87 | Not authorized | CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT | When the client uses token authentication or enhanced authentication, it is more appropriate to use 0x87 to indicate that the client is not authorized to connect than 0x86.When the client performs operations such as publishing and subscribing, if the authorization check of the server is not passed, the server can also specify the Reason Code 0x87 in the response packet such as PUBACK, to indicate the authorization result. |
| 0x88 | Server unavailable | CONNACK | Only used in the CONNACK packets to indicate to the client that the current server is unavailable. For example, it could indicate that the authentication service of the server is experiencing issues and cannot accept new clients. |
| 0x89 | Server busy | CONNACK, DISCONNECT | It shows the client that the server is busy, please try again later. |
| 0x8A | Banned | CONNACK | Only used for CONNACK packets, indicating that the client is prohibited from logging in. For example, the server detects the abnormal connection behavior of the client, so the Client ID or IP address of the client is added to the blacklist, or the background administrator manually blocks the client. Of course, the above usually depends on the specific server implementation. |
| 0x8B | Server shutting down | DISCONNECT | Only used for DISCONNECT packets, and only the server can use it.If the server is or is about to shut down, it can actively send a DISCONNECT packet with Reason Code 0x8B to inform the client that the connection is terminated because the server is shutting down.This can help the client avoid continuing to initiate a connection request to the server after the connection is closed. |
| 0x8C | Bad authentication method | CONNACK, DISCONNECT | When the server does not support the enhanced authentication method specified by the client, or the client uses a different authentication method from the previous authentication during re-authentication, the server will send a CONNACK or DISCONNECT packet with Reason Code 0x8C. |
| 0x8D | Keep Alive timeout | DISCONNECT | Only used for DISCONNECT packets, and only the server can use it.If the client fails to maintain communication within 1.5 times the Keep Alive time, the server will send a DISCONNECT packet with Reason Code 0x8D and close the network connection. |
| 0x8E | Session taken over | DISCONNECT | Only used for DISCONNECT packets, and only the server can use it.When the client connects to the server, if there is already a client connection using the same Client ID in the server, then the server will send a DISCONNECT packet with Reason Code 0x8E to the existing client, indicating that the session has been taken over by the new client. The server then closes the network connection for the current client.Regardless of whether the Clean Start in the new client connection is 0 or 1, the server will use this Reason Code to indicate to the existing client that the session has been taken over. |
| 0x8F | Topic Filter invalid | SUBACK, UNSUBACK, DISCONNECT | The topic filter is well-formed, but not accepted by the server. For example, the level of the topic filter exceeds the maximum limit allowed by the server, or the topic filter contains characters not accepted by the current server, such as spaces. |
| 0x90 | Topic Name invalid | CONNACK, PUBACK, PUBREC, DISCONNECT | The topic name is well-formed, but not accepted by the client or server. |
| 0x91 | Packet Identifier in use | PUBACK, PUBREC, SUBACK, UNSUBACK | This means that the Packet ID received in the packet is already in use. For example, if the sender sends a QoS 1 packet with Packet ID 100, but the receiver believes there is a QoS 2 packet using the same Packet ID that has not yet completed its message flow.This usually indicates that the current session state between the client and server is not matching, and it may be necessary to reset the session state by setting Clean Start to 1 and reconnecting. |
| 0x92 | Packet Identifier not found | PUBREL, PUBCOMP | Indicates that no corresponding Packet ID is found, which only occurs during the QoS 2 packet exchange process. For example, when the receiver replies with a PUBREC packet, the sender does not find a PUBLISH packet waiting for confirmation with the same Packet ID, or when the sender sends a PUBREL packet, the receiver does not find a PUBREC packet with the same Packet ID.This usually means that the current session state between the client and the server does not match, and it may be necessary to reset the session state by setting Clean Start to 1 and reconnecting. |
| 0x93 | Receive Maximum exceeded | DISCONNECT | Only used for DISCONNECT packets, indicating that the maximum received value has been exceeded.MQTT 5.0 adds a flow control mechanism. When connecting, the client and the server agree on the number of reliable messages they are willing to process concurrently through the Receive Maximum property (QoS > 0).So once the number of unconfirmed messages the sender sends exceeds this limit, the receiver will send a DISCONNECT packet with Reason Code 0x93 and close the network connection. |
| 0x94 | Topic Alias invalid | DISCONNECT | Only used for DISCONNECT packets, indicating that the subject alias is invalid.If the topic alias value in the PUBLISH packet is 0 or greater than the maximum topic alias agreed upon during the connection, the receiver will regard this as a protocol error, and it will send a DISCONNECT packet with a Reason Code of 0x94 and then close the network connection. |
| 0x95 | Packet too large | CONNACK, DISCONNECT | It is used to indicate that the packet exceeds the maximum allowable size. The maximum packet size allowed by the client and the server can be specified in the Maximum Packet Size attribute in the CONNECT and CONNACK packets.When one party sends a too-large packet, the other party will send a DISCONNECT packet with Reason Code 0x95, and then close the network connection.Since the client can set the will message when connecting, the CONNECT packet may also exceed the maximum message size limit that the server can handle. In this case, the server must use this Reason Code in the CONNACK packet. |
| 0x96 | Message rate too high | DISCONNECT | Only used for DISCONNECT packets, indicating that the maximum message publication rate allowed has been exceeded.It's important to note the difference between this Reason Code and "Quota exceeded". Message rate limits the speed of message publication, such as the maximum number of messages that can be published per second. On the other hand, Quota restricts the allocation of resources, such as the maximum number of messages a client can publish in a day. However, a client might exhaust its quota within an hour. |
| 0x97 | Quota exceeded | CONNACK, PUBACK, PUBREC, SUBACK, DISCONNECT | Used to indicate that a quota limit has been exceeded.The server may limit the sending quota of the publisher, such as allowing a maximum of 1000 messages to be forwarded daily. When the publisher exhausts the quota, the server will use this Reason Code in acknowledgment packets such as PUBACK to remind the publisher.On the other hand, the server may also limit the number of connections and subscriptions of the client. When this limit is exceeded, the server will indicate to the client that the quota is currently exceeded through a CONNACK or SUBACK packet.Some strict clients and servers may choose to send a DISCONNECT packet and then close the connection when they find that the peer has exceeded the quota. |
| 0x98 | Administrative action | DISCONNECT | Only used for DISCONNECT packets, indicate to the client that the connection has been closed due to a management operation, such as an administrator kicking out the client connection in the background. |
| 0x99 | Payload format invalid | CONNACK, PUBACK, PUBREC, DISCONNECT | When the Payload Format Indicator property is included in the packet, the receiver can check whether the payload format in the message matches this property. If they do not match, the receiver must send an acknowledgment packet with Reason Code 0x99.Some strict clients or servers may directly send a DISCONNECT packet and then close the network connection.If there is a problem with the will message in the CONNECT packet, the server will send a CONNACK packet with Reason Code 0x99 and then close the network connection. |
| 0x9A | Retain not supported | CONNACK, DISCONNECT | When the server does not support retained messages, but the client sends them, the server will send it a DISCONNECT packet with Reason Code 0x9A and then close the network connection.Since the client can also set the will message as retained when connecting, the server may also use this Reason Code in the CONNACK packet. |
| 0x9B | QoS not supported | CONNACK, DISCONNECT | Used to indicate that the current QoS level is not supported. If the QoS specified by the client in the message (including the will message) is greater than the maximum QoS supported by the server, the server will send a DISCONNECT or CONNACK packet with Reason Code 0x9B and close the network connection.In most cases, this Reason Code is used by the server. But when the client receives a message that is not from a subscription, and the QoS of the message is greater than the maximum QoS it supports, it will also send a DISCONNECT packet with Reason Code 0x9B and then close the network connection. This situation usually means that there may be a problem with the implementation of the server. |
| 0x9C | Use another server | CONNACK, DISCONNECT | The server uses this Reason Code in the CONNACK or DISCONNECT packet to inform the client that it should temporarily switch to another server.If another server is not known by the client, then this Reason Code also needs to be used together with the Server Reference property to inform the client of the address of the new server. |
| 0x9D | Server moved | CONNACK, DISCONNECT | The server uses this Reason Code in the CONNACK or DISCONNECT packet to inform the client that it should permanently switch to another server.If another server is not known by the client, then this Reason Code also needs to be used together with the Server Reference property to inform the client of the address of the new server. |
| 0x9E | Shared Subscriptions not supported | SUBACK, DISCONNECT | When the server does not support shared subscription, but the client tries to establish a shared subscription, the server can send a SUBACK packet with Reason Code 0x9E to reject the subscription request, or it can directly send a DISCONNECT packet with Reason Code 0x9E and then close the network connection. |
| 0x9F | Connection rate exceeded | CONNACK, DISCONNECT | Used to indicate that the client has exceeded the connection rate limit. The server can limit the connection rate of the client. When the client connects too fast, the server can send a CONNACK packet with Reason Code 0x9F to reject the new connection.Of course, this is not an absolute scenario. As not all clients will wait for a while before reconnecting, some server implementations may choose to temporarily suspend the connection instead of returning a CONNACK. |
| 0xA0 | Maximum connect time | DISCONNECT | Only used for DISCONNECT packets, and only the server can use it.For security reasons, the server can limit the maximum connection time of the client in a single authorization. For example, when using JWT authentication, the client connection should not continue after the JWT expires.In this case, the server can send a DISCONNECT packet with Reason Code 0xA0 to indicate to the client that the connection is closed because the authorized maximum connection time has been exceeded. After receiving the DISCONNECT packet containing this Reason Code, the client can re-obtain the authentication credentials and request the connection again. |
| 0xA1 | Subscription Identifiers not supported | SUBACK, DISCONNECT | When the server does not support the subscription identifier, but the client's subscription request contains the subscription identifier, the server can send a SUBACK packet with Reason Code 0xA1 to reject the subscription request, or directly send a DISCONNECT packet with Reason Code 0xA1 and then close the network connection. |
| 0xA2 | Wildcard Subscriptions not supported | SUBACK, DISCONNECT | When the server does not support wildcard subscription, but the client's subscription request contains topic wildcards, the server can send a SUBACK packet with Reason Code 0xA2 to reject the subscription request, or directly send a DISCONNECT packet with Reason Code 0xA2 and then close the network connection. |
Try EMQX Cloud for Free
Get Started →
A fully managed MQTT service for IoT