Paho MQTT "Unsupported callback API version" error

Question

I am trying to implement Paho Python MQTT and connect to an online broker but the code seems to through an error.

ValueError: Unsupported callback API version: version 2.0 added a callback_api_version, see migrations.md for details

I was trying to implement a simple paho client example from the given website; the following will reproduce the issue:

from paho.mqtt import client as mqtt_client
import random

broker = 'broker.emqx.io'
port = 1883
topic = "python/mqtt"
client_id = f'python-mqtt-{random.randint(0, 1000)}'
client = mqtt_client.Client(client_id)

Answer 1

Release 2.0.0 of the Paho Python MQTT includes breaking changes; this means that code written for v1.x will not work without some (minimal) modifications. As v2.0.0 was only released a few days ago (11th Feb 2024) most examples, including the one you reference, will not work.

The changes required are documented here (or here); in your case it's likely that the only change needed is add a single parameter changing:

client = mqtt_client.Client(client_id)

to:

client = mqtt_client.Client(mqtt_client.CallbackAPIVersion.VERSION1, client_id)

This will configure the library to use the v1 callback API (as used with older versions of the library). I would recommend reading the document linked above and planning to migrate to CallbackAPIVersion.API_VERSION2.

An alternative option would be to install a v1 release (v1.6.1 is the latest; pip install "paho-mqtt<2.0.0" will install this). V2 does include quite a few fixes/enhancements so it is worth considering using that version.

Update 2024-05

Version 2.1 has now been released. This now defaults to CallbackAPIVersion.VERSION1 which will, in limited circumstances, mean old code still runs. This will not help if you pass positional parameters to client (e.g. mqtt.Client("thisIsMyClientID")) and specifying a callback version is recommended to avoid future confusion (because this has an impact on the parameters passed to callbacks).