Coverage for src / zmqtt / errors.py: 100%
39 statements
« prev ^ index » next coverage.py v7.13.4, created at 2026-11-12 08:49 +0000
« prev ^ index » next coverage.py v7.13.4, created at 2026-11-12 08:49 +0000
1from zmqtt._internal.packets.properties import ConnAckProperties
4class MQTTError(Exception):
5 """Base class for all zmqtt exceptions."""
8# CONNACK codes for a refusal the broker may lift on its own, such as while it
9# boots or sheds load. MQTT 3.1.1 codes are below 0x80 and MQTT 5 codes are
10# 0x80 and above, so one set covers both versions. 0x9C (Use another server)
11# and 0x9D (Server moved) are left out: MQTT 5 section 4.11 says to switch
12# server rather than retry the same one.
13_TRANSIENT_CONNACK_CODES = frozenset(
14 {
15 0x03, # MQTT 3.1.1: Server unavailable
16 0x88, # MQTT 5: Server unavailable
17 0x89, # MQTT 5: Server busy
18 0x97, # MQTT 5: Quota exceeded
19 0x9F, # MQTT 5: Connection rate exceeded
20 },
21)
24class MQTTConnectError(MQTTError):
25 """CONNACK returned a non-zero return code."""
27 def __init__(self, return_code: int, *, properties: ConnAckProperties | None = None) -> None:
28 self.return_code = return_code
29 self.properties = properties
30 self.reason_string = properties.reason_string if properties is not None else None
31 self.user_properties = properties.user_properties if properties is not None else ()
32 self.server_reference = properties.server_reference if properties is not None else None
33 super().__init__(f"Connection refused: return code {return_code}")
35 @property
36 def is_transient(self) -> bool:
37 """Whether the broker may accept a later attempt without a config change.
39 True for "server unavailable", "server busy", "quota exceeded" and
40 "connection rate exceeded"; false for refusals such as bad credentials.
41 """
42 return self.return_code in _TRANSIENT_CONNACK_CODES
45class MQTTProtocolError(MQTTError):
46 """Unexpected or malformed packet received."""
49class MQTTQoSExceededError(MQTTError):
50 """A PUBLISH requested a QoS higher than the server's advertised Maximum QoS.
52 Raised locally, before the packet is sent — the server would otherwise
53 have to reject or drop it (MQTT 5.0 §3.2.2.3.4).
54 """
56 def __init__(self, requested: int, maximum: int) -> None:
57 self.requested_qos = requested
58 self.maximum_qos = maximum
59 super().__init__(f"Requested QoS {requested} exceeds the server's Maximum QoS {maximum}")
62class MQTTRetainNotAvailableError(MQTTError):
63 """A retained PUBLISH was requested but the server does not support retained messages.
65 Raised locally, before the packet is sent, when CONNACK set Retain Available
66 to 0 (MQTT 5.0 §3.2.2.3.5). The connection stays open.
67 """
69 def __init__(self) -> None:
70 super().__init__("The server does not support retained messages (Retain Available is 0)")
73class MQTTDisconnectedError(MQTTError):
74 """Connection lost unexpectedly."""
77class MQTTTimeoutError(MQTTError):
78 """An MQTT operation did not complete within the allotted time."""
81class MQTTSubscribeError(MQTTError):
82 """The broker rejected one or more filters in a SUBSCRIBE (SUBACK >= 0x80).
84 Most commonly an authorization denial: without this error the subscription
85 looks successful and silently never receives anything.
86 """
88 def __init__(self, failures: dict[str, int]) -> None:
89 self.failures = failures
90 rendered = ", ".join(f"{f!r} (0x{code:02X})" for f, code in failures.items())
91 super().__init__(f"Broker rejected subscription: {rendered}")
94class MQTTPublishError(MQTTError):
95 """The broker rejected a QoS 1/2 publish.
97 *reason_name* is the spec's name for *reason_code* (``None`` for a code
98 zmqtt does not recognize). *reason_string* is the broker's optional Reason
99 String property.
100 """
102 def __init__(
103 self,
104 reason_code: int,
105 reason_name: str | None,
106 reason_string: str | None,
107 ) -> None:
108 self.reason_code = reason_code
109 self.reason_name = reason_name
110 self.reason_string = reason_string
111 named = f"0x{reason_code:02X} {reason_name}" if reason_name else f"0x{reason_code:02X}"
112 detail = f": {reason_string}" if reason_string else ""
113 super().__init__(f"Broker rejected publish ({named}){detail}")
116class MQTTInvalidTopicError(MQTTError):
117 """Topic string or topic filter failed MQTT validation."""