Understanding MQTTv5 Topic Aliases

MQTTv5 Topics are essentially the same as those in v3.1.1 (See Understanding MQTT topics) ,but two new features have been introduced in v5. They are:

  • Topic aliases
  • Shared Topics

In this tutorial we will be covering topic aliases.

Topic aliases

Topic aliases were introduced in MQTT-SN and are a mechanism for reducing the size of published packets by reducing the size of the topic field.

Once established a topic alias can be used in place of a topic string.

So if the topic houses/house1/upstairs/light1 had an alias or 1 then this could be used in place of the topic string when publishing messages.

Topic Aliases Client to Server

How many topic aliases the client can publish on is determined by the server. Mosquitto is set to 10 topic aliases by default.

Topic Aliases Server to Client

How many topic aliases the server can publish on is determined by the client. Most clients use 0 by default. Which means that the server isn’t allowed to use topic aliases when publishing messages to the client.

Topic Alias Process

The topic alias for a topic is set in the publish message.

So a client  will publish a message on a topic, and indicate that the topic will use an alias in the future.

Here is an example publish using Python using the paho 1.5.1 client:

properties.TopicAlias=1 #set the topic alias

Topic Alias Restrictions

Both the server and the client can impose restrictions on the number of topic aliases it will support on a connection.

For mosquitto the default is 10 and for the client it is 0.(no topic aliases supported)

You can see the number of aliases the server support in the CONNACK message.


The client indicates the client maximum  in the connection properties field.

In either case a value of 0 or not included means the client/server doesn’t support topic aliases.

If a client tries to publish using a topic alias and the number of topic aliases has been exceeded then the connection is dropped by the server.

The screen shot below shows the server has a maximum topic alias of 0 so when I try to publish the client gets disconnected.


Publishing and Subscribing Using Topic Aliases

Topic aliases are only available on publish, and not on subscribe.

So if we have a topic called mytopicalias then the subscriber must subscribe using the full topic name whereas the publisher can assign an alias to the topic name and publish using the alias.

So the process for the publisher is:

publish message on topic and set the topic alias

Python example code:

properties.TopicAlias=1 #set the topic alias

Publish subsequent messages using a blank topic and a topic alias

Python example code:

properties.TopicAlias=1 #set the topic alias
client_pub.publish('', msg_out1,qos=0,properties=properties)

Notice the empty topic entry above

The process for the subscriber is  a normal subscribe using the full topic name.
Python example code:



If you attempt to publish using a topic alias and they are not supported or you have exceed the max number on the server you will get disconnected as shown below:



Topic aliases are designed to reduce the size of transmitted messages and hence network traffic. In most cases they are not really necessary but if there are many clients publishing frequently then they could potentially substantially reduce the network traffic. See MQTT Topic and Payload Design Notes

Related Tutorials and Resources

Please rate? And use Comments to let me know more


  1. Hi Steve,

    thank you for that great explanation. Did I understand you right, if a client sets a higher `topic_alias` value than the broker, the broker will always end the connection? Or is that a peculiarity of mosquitto?

    What is the biggest amount of topic alias I can set at the broker?
    Will every client can send 10000 different topics if I set the topic_alias at the mosquitto to 10000 or is that the sum of all topics the broker can map to an id ?

    I would appreciate an answer from you 😉


    1. This is taken from the mosquitto docs
      max_topic_alias number

      This option sets the maximum number topic aliases that an MQTT v5 client is allowed to create. This option applies per listener. Defaults to 10. Set to 0 to disallow topic aliases. The maximum value possible is 65535.

      So max 65,535 per listener not per client so if you had 65,535 clients then each would only be able to create 1.
      After reading the spec it says that the client must not send a value greater than the maximum. It does not say what action to take so it could just ignore it so I would guess it is broker dependent.
      I haven’t tested it with mosquitto yet.

Leave a Reply

Your email address will not be published. Required fields are marked *