How do MQTT 5.0 reason codes work?

A reason code is a single byte returned in acknowledgement packets (CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK) and in DISCONNECT and AUTH. Values from 0x00 to 0x7F indicate success or normal operation, while values from 0x80 to 0xFF indicate an error. The same byte can appear in several packet types.

What does MQTT reason code 0x87 mean?

0x87 is Not authorized. It tells the client that the server refused the operation on authorization grounds, whether that is a CONNECT (the account may not connect), a PUBLISH (no write permission on the topic), or a SUBSCRIBE (no read permission). Fixing it requires changing broker ACLs or credentials, not retrying.

Why does 0x00 mean different things in different packets?

0x00 always sits in the success range, but its label is packet-specific. In CONNACK and most acknowledgements it is Success, in SUBACK it is Granted QoS 0, and in DISCONNECT it is Normal disconnection. The numeric value is the same; the human-readable name depends on context, which is why the applicable packets are listed.

What is the difference between 0x10 No matching subscribers and an error?

0x10 is in the success range. When a PUBACK or PUBREC returns 0x10, the publish was accepted and processed correctly; it simply had no subscribers whose filters matched the topic at that moment. It is informational, not a failure, so the client should not treat it as a delivery error.

Is this MQTT reference private?

Yes. The full reason-code table, search and filtering all run locally in your browser with no account and no network calls. Nothing you type is uploaded.

MQTT Reason Codes Reference

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

The MQTT Reason Codes Reference is a searchable lookup for the single-byte reason codes introduced in MQTT 5.0. Unlike MQTT 3.1.1, which had a tiny set of CONNACK return codes, version 5.0 uses a unified reason-code byte across nearly every acknowledgement and the DISCONNECT and AUTH packets — so the same 0x87 can explain a refused connect, a blocked publish, or a denied subscribe.

How it works

Every MQTT 5.0 control packet that reports a result carries a one-byte reason code. The high bit splits the range cleanly:

0x00 - 0x7F   Success / normal operation
0x80 - 0xFF   Error / failure

Acknowledgement packets — CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK — plus DISCONNECT and AUTH each return one. The label attached to a value can vary by packet: 0x00 is Success in CONNACK, Granted QoS 0 in SUBACK, and Normal disconnection in DISCONNECT. This tool keeps the full table in your browser and filters it by hex value, decimal value, name, packet type or description.

Example and tips

A clean session looks like CONNECT → CONNACK 0x00 Success → SUBSCRIBE → SUBACK 0x01 Granted QoS 1 → PUBLISH → PUBACK 0x00 Success. Watch the success-range informational codes: 0x10 (no matching subscribers) and 0x11 (no subscription existed) are not errors, so don’t alert on them. On the error side, a server can now send a DISCONNECT to the client with a reason such as 0x8D (Keep Alive timeout), 0x8E (Session taken over) or 0x95 (Packet too large) — read that byte to learn why the broker dropped you rather than guessing.