Reconnection
Default behaviour
Reconnection is enabled by default and applies to both the initial connection and any subsequent connection loss. When a network-level error (OSError) occurs, including during an established connection after an RST, route change, or VPN transition, the client waits and retries with exponential back-off. When a running connection drops (MQTTDisconnectedError or MQTTTimeoutError), it reconnects and re-subscribes automatically. Your async for msg in sub loop keeps waiting and resumes delivering messages once the connection is restored.
A broker refusal (MQTTConnectError) is retried like a network error only when it is transient: "server unavailable" (3.1.1 code 3, MQTT 5 0x88), "server busy" (0x89), "quota exceeded" (0x97) and "connection rate exceeded" (0x9F). A broker that is still starting up, or shedding load, sends these. These attempts count towards max_attempts. Any other refusal, such as bad credentials or not authorised, propagates immediately. MQTTConnectError.is_transient tells the two apart. To change which refusals are retried, see Retrying other refusals.
Your application code does not need to handle reconnection at all in the common case.
ReconnectConfig
from zmqtt import ReconnectConfig
config = ReconnectConfig(
enabled=True,
initial_delay=1.0, # seconds before first retry
max_delay=60.0, # cap on retry interval
backoff_factor=2.0, # multiplier applied after each failure
max_attempts=5, # None = retry indefinitely
)
| Field | Default | Description |
|---|---|---|
enabled |
True |
Enable/disable automatic reconnection |
initial_delay |
1.0 |
Seconds to wait before the first reconnect attempt |
max_delay |
60.0 |
Maximum delay between attempts |
backoff_factor |
2.0 |
Each failure multiplies the delay by this factor |
max_attempts |
5 |
Total connection attempts before giving up. None retries indefinitely |
retry_refusal |
None |
Decides per refused CONNACK whether to retry it. None retries only transient refusals |
With the default limit of five total attempts, failed attempts are separated by
delays of 1 s, 2 s, 4 s, and 8 s. With max_attempts=None, retries continue and
the delay eventually caps at 60 s.
Retrying other refusals
retry_refusal replaces the default decision for every refused CONNACK. It
receives the MQTTConnectError and returns True to retry. Retries still use
the back-off and count towards max_attempts.
Some brokers refuse with "not authorised" while they start up. RabbitMQ, for example, sends it while a vhost is starting or before a user's permissions are applied. To retry that as well:
from zmqtt import MQTTConnectError, ReconnectConfig
NOT_AUTHORIZED = {0x05, 0x87} # MQTT 3.1.1 and MQTT 5
def retry_refusal(refusal: MQTTConnectError) -> bool:
return refusal.is_transient or refusal.return_code in NOT_AUTHORIZED
config = ReconnectConfig(max_attempts=None, retry_refusal=retry_refusal)
The MQTT 3.1.1 and MQTT 5 code spaces differ (3.1.1 code 5 is MQTT 5 0x87),
so check both when the client may use either version. Retrying a refusal the
broker will never lift, such as bad credentials, only delays the error; brokers
may also treat repeated attempts as abuse (MQTT 5 section 5.4.8).
Passing config to create_client()
from zmqtt import create_client, ReconnectConfig
async with create_client(
"localhost",
reconnect=ReconnectConfig(initial_delay=0.5, max_delay=30.0, max_attempts=None),
) as client:
...
Handling failed connection recovery
Use on_connection_recovery_failed when application code needs to observe that
a running client cannot restore its connection:
from zmqtt import ReconnectConfig, create_client
async def connection_recovery_failed() -> None:
print("MQTT connection could not be restored")
async with create_client(
"localhost",
reconnect=ReconnectConfig(max_attempts=5),
on_connection_recovery_failed=connection_recovery_failed,
) as client:
...
The async callback is awaited exactly once after a previously established
connection cannot be restored. It is not called when the initial connection
fails or when the client is disconnected cleanly. Initial connection failures
still propagate from connect() or the async context manager entry.
After the callback returns, the client stops reconnecting and the terminal connection error is propagated to active subscription iterators. Use the callback to notify the component that owns the client lifecycle when it needs to take further action.
How subscriptions survive reconnect
Each Subscription is re-subscribed on the new connection automatically. The local message queue is preserved — messages that arrived before the disconnect are still in the queue and will be delivered to your code. New messages start flowing once the broker confirms the re-subscribe.
This preserves the local subscription lifecycle, not every message published while the client was offline. Delivery during the gap depends on QoS and the broker-side session; durable redelivery requires the persistent-session settings described in Manual Acknowledgement. See Persistent Sessions for startup replay and subscription-ordering details.
Disabling reconnection
from zmqtt import create_client, ReconnectConfig
async with create_client(
"localhost",
reconnect=ReconnectConfig(enabled=False),
) as client:
...
With reconnection disabled, the client stops on the first connection loss and
invokes on_connection_recovery_failed, if configured. MQTTDisconnectedError
is raised on the next call to publish(), ping(), entering a new subscribe()
context, or waiting for a message from an active subscription.
See also: Error Handling · Subscribing · Connecting