MQTT 5 Reason Codes: Complete Reference Table with Causes and Fixes

MQTT reason codes are the single-byte status values that MQTT 5 brokers and clients put into acknowledgements and DISCONNECT packets to say exactly what happened. This reference lists every code, which packets can carry it, what usually triggers it and how to fix it, so you can turn a cryptic 0x87 or 0x97 in your logs into a concrete next step.

How MQTT Reason Codes Work

MQTT 3.1.1 had only a handful of status values: six CONNACK return codes and a single failure value (0x80) in SUBACK. Everything else, such as a rejected publish or a broker-side disconnect, was silent; the connection just closed. MQTT 5 replaced this with a shared set of reason codes used across CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT and AUTH. It is one of the most practical MQTT 5 features for anyone operating devices in the field.

Two rules make the table easy to read:

• Values below 0x80 mean success or a non-error outcome, such as "granted QoS 1" or "no matching subscribers".
• Values of 0x80 and above mean failure. The packet that carries the code tells you which operation failed.

Many packets can also carry a Reason String property, a human-readable explanation from the sender. Always log it when present; it often contains the exact limit that was hit.

Success and Informational Codes

A SUBACK granting a lower QoS than you requested is not an error. If you ask for QoS 2 and get 0x01, the broker's maximum QoS is 1 for your connection, and messages will arrive at QoS 1 at most.

Error Reason Codes Reference

Note that some codes, such as 0x8D and 0x8E, appear only in a DISCONNECT sent by the broker. Others, like 0x84 to 0x88, can only appear in CONNACK because they describe why the connection was refused in the first place.

Mapping MQTT 3.1.1 Return Codes to MQTT 5

If you support both protocol versions, this mapping keeps your error handling consistent. The detailed walkthrough is in the guide to MQTT CONNACK return codes.

Logging MQTT Reason Codes in Python

With paho-mqtt 2.x and CallbackAPIVersion.VERSION2, every callback receives a ReasonCode object. Its string form is the spec name and .value is the numeric code, which is exactly what you want in logs:

import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, reason_code, properties):
    print(f"CONNACK: {reason_code} (0x{reason_code.value:02X})")
    if reason_code.is_failure:
        return
    client.subscribe("connectmq/demo/b7d2/#", qos=2)

def on_subscribe(client, userdata, mid, reason_code_list, properties):
    for rc in reason_code_list:
        print(f"SUBACK: {rc} (0x{rc.value:02X})")

def on_disconnect(client, userdata, flags, reason_code, properties):
    reason = getattr(properties, "ReasonString", None) if properties else None
    print(f"DISCONNECT: {reason_code} (0x{reason_code.value:02X}) {reason or ''}")

client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id="reason-demo-b7d2",
    protocol=mqtt.MQTTv5,
)
client.on_connect = on_connect
client.on_subscribe = on_subscribe
client.on_disconnect = on_disconnect
client.connect("broker.connectmq.com", 1883, keepalive=30)
client.loop_forever()

Run this against the public MQTT test broker and you will see Success on connect and a granted QoS in SUBACK. Try subscribing to an invalid filter such as connectmq/demo/b7d2/#/x to see 0x8F Topic Filter invalid in action. With MQTT.js, the same information is in connack.reasonCode, the granted array of the subscribe callback, and the disconnect event packet.

Debugging Workflow by Reason Code

A practical order for investigating a failure:

1. Identify the packet. A code in CONNACK is a connection problem; in SUBACK, a subscription problem; in DISCONNECT, a runtime problem.
2. Read the Reason String. It usually narrows the cause to a specific limit or rule.
3. Check credentials and identity first for 0x85, 0x86 and 0x87. The guide to fixing MQTT connection refused: not authorized covers this in depth.
4. Check limits for 0x93, 0x95, 0x96 and 0x97: message size, rate, connection count and in-flight messages.
5. Check fleet hygiene for 0x8E: duplicate client IDs are the most common cause of disconnect loops.

Reason Codes on ConnectMQ

ConnectMQ supports MQTT 3.1.1 and 5.0, so MQTT 5 clients receive the reason codes above. Plan quotas surface as 0x97 Quota exceeded, for example when a free Serverless broker already has its maximum of 25 connections. Plan features matter too: the free plan grants QoS up to 1, so a QoS 2 subscription is granted at a lower QoS in SUBACK, while QoS 2 and shared subscriptions come with the paid Serverless plan. Repeated failed logins are treated as suspicious, and the source IP can be blocked, so never leave a client retrying bad credentials in a tight loop.

For background on what an MQTT broker does with these codes, or the full protocol in context, see the MQTT tutorial.

Debug Faster with ConnectMQ

A managed MQTT broker with an in-browser client and live topic explorer makes it much quicker to reproduce a failing publish or subscription. Create a free Serverless broker at app.connectmq.com, no credit card needed, and test your error handling against real MQTT 5 responses.

Frequently Asked Questions

What is the difference between a reason code and a return code?

Return code is the MQTT 3.1.1 term for the six CONNACK values. MQTT 5 generalised the idea into reason codes that appear in almost every acknowledgement and in DISCONNECT.

Which reason codes mean success?

Any value below 0x80. That includes 0x00 Success, 0x01 and 0x02 for granted QoS, and informational values such as 0x10 No matching subscribers.

What does MQTT reason code 0x97 mean?

0x97 is Quota exceeded: the client hit a limit such as maximum connections or a plan restriction. Reduce usage or move to a plan with higher limits.

Do MQTT 3.1.1 clients receive MQTT 5 reason codes?

No. A 3.1.1 connection only gets the classic CONNACK return codes and the 0x80 SUBACK failure value. Connect with protocol version 5 to receive detailed reason codes.