MQTT Topic Aliases: Rebuild Connection-Local State After Every Reconnect

Reset topic-alias state whenever a new MQTT network connection begins, even if the previous MQTT session resumes. Send a full topic name when establishing a mapping on that connection, and omit the topic only after the mapping has been established in the ordered send stream. An alias is connection-local compression state, not a durable topic identity.

This guide uses the OASIS MQTT Version 5.0 Standard, 7 March 2019, especially sections 3.1.2.11.5, 3.2.2.3.8, 3.3.2.3.4 and 3.3.4. An original state model was executed locally. No MQTT broker, client library, packet codec or network connection was tested; deployment qualification must use the selected implementations.

Keep the two directions independent

The Topic Alias Maximum in CONNECT limits aliases the client will accept from the server. The corresponding CONNACK property limits aliases the server will accept from the client. An absent maximum defaults to zero, meaning aliases are not accepted in that direction. Do not apply the outbound limit to the inbound table simply because both properties have the same name.

Maintain separate inbound and outbound maps, each tied to one connection generation. Alias one can identify an uplink topic in one map and a different downlink topic in the other. Include the direction and connection generation in diagnostic records; an alias number alone is ambiguous.

Make mapping installation an explicit state transition

A PUBLISH containing a nonempty topic and a valid alias installs or replaces that mapping. A later PUBLISH can use the mapped alias with an empty topic name. Sending the same alias with another nonempty topic changes its meaning for subsequent alias-only packets. These transitions belong to the network connection, independently of application subscription or persistence policy.

For a hypothetical telemetry client, alias one might first map to “lab/device07/temperature.” A full-topic publication establishes it; later publications can use alias one alone. If the client reassigns one to “lab/device07/pressure,” future alias-only messages refer to pressure. An old queued message that assumed the previous mapping must not silently inherit the new meaning.

Serialize mapping changes with packet emission. A table update in one producer thread is not proof that the corresponding full-topic packet has already preceded another thread’s alias-only packet on the connection. One encoding/send owner or an equivalent ordered reservation protocol makes that obligation easier to inspect.

Reset on reconnection, not only on clean-session changes

The standard explicitly forbids carrying alias mappings into another network connection. A reconnect path that restores subscriptions or in-flight application state must therefore still initialize fresh alias maps and read the new negotiated maxima. Session Present is not permission to reuse old alias-only encodings.

Keep a durable or queued message’s logical topic separately from its compressed packet representation. When retransmission or replay crosses a connection boundary, rebuild the connection-dependent encoding using the new map and limit. This does not replace the separate MQTT QoS retransmission rules; it prevents an old alias reference from being mistaken for a portable topic.

Also invalidate old connection callbacks and pending encoded buffers according to the client’s lifecycle design. A stale sender must not emit an alias-only packet into a new connection merely because the socket wrapper reused the same application handle.

Classify invalid aliases correctly

Incoming publication condition	MQTT 5.0 classification
Alias zero	Topic Alias invalid, reason 0x94
Alias exceeds the receiving endpoint’s advertised maximum	Topic Alias invalid, reason 0x94
Valid-range alias, empty topic, no mapping yet	Protocol Error, reason 0x82
Valid-range alias with nonempty topic	Establish or replace that alias mapping

Section 3.3.4 distinguishes the first two cases from an unknown mapping used with an empty topic. Preserve that distinction in tests and diagnostics. A valid number does not establish a mapping. Conversely, increasing the maximum does not repair an alias-only packet sent before its full-topic installation.

On a live implementation, capture the actual disconnect outcome under the standard’s error-handling rules and the library’s reporting interface. The local model’s numeric classification is not evidence that a particular server emitted a packet with that reason code.

Use connection-boundary test vectors

The executed Python model covered twelve assertions: installation, alias-only use, reassignment and subsequent use, use at the advertised maximum, zero alias, above-maximum alias, reset followed by unknown alias, reinstallation, absent maximum, full-topic publication without alias and independent directional maps.

The model rejected zero and above-maximum aliases with classification 0x94, and an alias-only publication after reset with 0x82. It correctly resolved a reused alias after reassignment and allowed full-topic publication without alias when the maximum was zero. These are tests of the original state model, not a broker conformance claim.

The model deliberately omits UTF-8 validation, duplicate properties, full packet parsing, QoS state and transport failures. Those omissions define the next integration tests rather than disappearing behind a passing model result.

Qualify the actual client and broker

1. Record both versions and the CONNECT/CONNACK alias maxima in each direction.
2. Capture a full-topic installation followed by alias-only use and confirm resolved topics.
3. Reassign an alias while multiple producers have queued messages; verify serialization preserves each logical topic.
4. Reconnect with session state retained and confirm that the first aliased publication reinstalls its mapping.
5. Reconnect to a server configuration with a smaller or zero maximum and verify the sender adapts.
6. Inject the invalid cases in an isolated namespace and compare observed disconnect reasons with the expected categories.

Acceptance requires that every alias-only packet can be explained by an earlier mapping on the same connection and in the same direction. Keep the original logical topic visible in the test ledger, even when wire compression removes it. That evidence makes reconnect failures and accidental topic reassignment diagnosable without assuming a short packet still means what it meant on the previous connection.