Paho MQTT Unsupported Callback API Version Error

Problem Statement

When updating or installing the Paho MQTT Python client library (paho-mqtt), users may encounter the error:

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

This occurs when:

1. Using paho-mqtt version 2.0.0 or newer
2. Instantiating the client with older syntax: client = mqtt_client.Client(client_id)
3. Running code samples written for Paho MQTT versions before 2.0.0

The root cause is a breaking change introduced in paho-mqtt version 2.0.0, which requires explicit specification of the callback API version.

Recommended Solutions

1. Create Client with Explicit Callback Version (Preferred)

Specify either VERSION1 (backward-compatible) or VERSION2 (current API) when creating the client:

from paho.mqtt import client as mqtt_client
import paho.mqtt.client as mqtt

# For backward compatibility (v1.x behavior)
client = mqtt_client.Client(mqtt.CallbackAPIVersion.VERSION1, client_id)

# For new implementations (current best practice)
client = mqtt_client.Client(mqtt.CallbackAPIVersion.VERSION2, client_id)

Recommendation

• Use VERSION1 for quick migration of existing code
• Prefer VERSION2 for new projects to access latest features

2. Adapt Callbacks for VERSION2 (Full Implementation)

When using VERSION2, modify callback signatures to match the new API:

import time
import paho.mqtt.client as mqtt
from paho.mqtt.client import CallbackAPIVersion

client = mqtt.Client(CallbackAPIVersion.VERSION2, client_id="test-client")

# Version 2 callback signatures
def on_connect(client, userdata, flags, reason_code, properties):
    print(f"Connected: reason_code={reason_code}, properties={properties}")
    client.subscribe("test/topic", qos=1)

def on_message(client, userdata, msg):
    print(f"{msg.topic}: {msg.payload.decode()}")

client.on_connect = on_connect
client.on_message = on_message

client.connect("broker.emqx.io", port=1883, keepalive=60)
client.loop_start()
time.sleep(1)
client.publish("test/topic", "Hello MQTT!", qos=1)
time.sleep(2)
client.loop_stop()

Callback Parameter Changes

VERSION2 callbacks include extra parameters:

• on_connect adds reason_code and properties
• on_subscribe adds reason_codes and properties
• Full migration guide: Official Migration Documentation

3. Temporary Workarounds

Downgrade Library (Not Recommended for Production)

Install previous version of paho-mqtt:

pip install "paho-mqtt<2.0.0"

Compatibility Layer for Existing Projects

Handle different library versions programmatically:

try:
    # Try new version API first
    from paho.mqtt.client import CallbackAPIVersion
    client = mqtt_client.Client(CallbackAPIVersion.VERSION1, client_id)
except (ImportError, AttributeError):
    # Fallback to old API
    client = mqtt_client.Client(client_id)

Additional Key Information

1. Version 2.1.0+ Behavior:
   Starting with v2.1.0, Paho defaults to VERSION1 if no callback version is provided
   (🎯 Still specify explicitly to avoid positional argument issues).

2. Why Migration is Needed:
   The API change resolves several design limitations in v1.x, including:

   • Better MQTT v5.0 support
   • Consistent callback signatures
   • Improved error handling

Best Practices Summary

Approach	When to Use	Recommendations
VERSION2	New applications	✅ Preferred for long-term usage
VERSION1	Quickly fix existing code	🔄 Plan migration to VERSION2
Downgrade	Temporary workaround	⚠️ Not recommended - misses security updates

Pro Tip

Always check the official migration guide when updating your MQTT clients.