MQTT cheat sheet

The numbers and names you look up while working with MQTT, on one page.

• QoS levels
• Control packet types
• Wildcards
• Default ports
• Retained messages
• Last Will and Testament
• Clean session, clean start and session expiry
• Keep alive
• MQTT 5 additions
• Reason codes
• $SYS topics

QoS levels

QoS	Guarantee	Packets	Duplicates
0	At most once. One send, no acknowledgement, no retry.	PUBLISH	No, but the message can be lost
1	At least once. Resent until acknowledged.	PUBLISH, PUBACK	Possible
2	Exactly once. Two-step handshake.	PUBLISH, PUBREC, PUBREL, PUBCOMP	No

QoS 0 suits frequent telemetry where a lost reading does not matter. QoS 1 suits most state and command traffic. QoS 2 is for commands that must not run twice. The MQTT QoS levels page goes into how each level behaves across a reconnect.

Control packet types

MQTT 5 defines 15 control packet types, values 1 to 15. MQTT 3.1.1 has 14, without AUTH. Value 0 is reserved in both.

Value	Name	Direction	Purpose
1	CONNECT	Client to broker	Connection request
2	CONNACK	Broker to client	Connection acknowledgement
3	PUBLISH	Either	Publish a message
4	PUBACK	Either	QoS 1 acknowledgement
5	PUBREC	Either	QoS 2 step 1
6	PUBREL	Either	QoS 2 step 2
7	PUBCOMP	Either	QoS 2 step 3
8	SUBSCRIBE	Client to broker	Subscribe request
9	SUBACK	Broker to client	Subscribe acknowledgement
10	UNSUBSCRIBE	Client to broker	Unsubscribe request
11	UNSUBACK	Broker to client	Unsubscribe acknowledgement
12	PINGREQ	Client to broker	Keep alive ping
13	PINGRESP	Broker to client	Keep alive reply
14	DISCONNECT	Either in MQTT 5, client only in 3.1.1	Graceful disconnect
15	AUTH	Either, MQTT 5 only	Extended authentication

Wildcards

+ matches one topic level. # matches the rest of the topic and must come last, so sport/# also matches sport. A pattern that starts with + or # does not match a topic starting with $, and neither is allowed in a topic you publish to. Try patterns in the wildcard tester.

Default ports

Port	Use
1883	MQTT over TCP, unencrypted. IANA registered.
8883	MQTT over TLS. IANA registered.
8080, 8081	MQTT over WebSocket, ws and wss. Broker convention.
9001	Mosquitto's usual WebSocket listener. Broker convention.

Only 1883 and 8883 are standard. Check the broker's listener configuration for the rest. More on the MQTT ports page.

Retained messages

A message published with the retain flag is stored by the broker, one per topic, and sent to every new subscriber at once. A new retained message replaces it. An empty retained payload deletes it. See how retained messages work and how to clear them.

Last Will and Testament

A message the client registers at CONNECT time with its own topic, payload, QoS and retain flag. The broker publishes it if the client drops without sending DISCONNECT. In MQTT 5 a Will Delay Interval holds it back, so a quick reconnect does not announce a false offline state.

Clean session, clean start and session expiry

MQTT 3.1.1 has one Clean Session flag. True discards subscriptions and queued QoS 1 and 2 messages on disconnect. False keeps them until the client returns.

MQTT 5 splits it in two. Clean Start says whether this connection resumes the old session. Session Expiry Interval says how many seconds the broker keeps the session after a disconnect. Zero means discard at once.

Keep alive

An interval in seconds agreed at CONNECT time. If nothing else has been sent within it, the client sends PINGREQ and the broker answers PINGRESP. If the broker hears nothing for one and a half times the interval, it treats the client as gone and publishes its Last Will.

MQTT 5 additions

Feature	What it does
User properties	Key and value string pairs on any packet, for application metadata.
Topic alias	A small integer that stands in for a topic string after the first publish.
Response topic and correlation data	Request and response over PUBLISH: where to reply, and how to match the reply.
Shared subscriptions	$share/group/topic splits messages between subscribers in the group.
Message expiry interval	Seconds after which the broker drops an undelivered message.
Reason codes	Every acknowledgement carries a specific code instead of pass or fail.
Receive maximum	How many QoS 1 and 2 messages each side allows in flight.

Reason codes

Below 0x80 is success, 0x80 and above is failure. The same numbering is used, with packet-specific subsets, in CONNACK, PUBACK, SUBACK, UNSUBACK and DISCONNECT.

Hex	Name	In practice
0x00	Success	Accepted
0x80	Unspecified error	Check the broker's logs
0x81	Malformed packet	The packet could not be parsed
0x82	Protocol error	The packet broke the specification, for example wrong flags
0x84	Unsupported protocol version	The broker does not speak the requested MQTT version
0x85	Client identifier not valid	Empty when not allowed, bad characters, or too long
0x86	Bad user name or password	Credentials wrong or missing
0x87	Not authorised	Credentials fine, this client is not allowed
0x88	Server unavailable	The broker cannot accept connections now
0x89	Server busy	Back off and retry
0x8A	Banned	Blocked, often after repeated failed authentication
0x97	Quota exceeded	A broker limit was hit, for example too many connections
0x99	Payload format invalid	The payload claims UTF-8 and is not
0x9C	Use another server	The broker wants this client elsewhere

$SYS topics

Brokers publish their own metrics under $SYS/: connected clients, message rates, uptime. It is a convention, not part of the specification, and every broker lays it out differently. A subscription to # does not include it; subscribe to $SYS/#. What each broker publishes is in the $SYS topics reference.

Frequently asked questions

MQTT Viewer shows QoS and retain on every message, publishes with MQTT 5 properties and turns $SYS topics into a status page. Download MQTT Viewer.