Skip to main content
Mqttable
Sign In

Open navigation

Mqttable
Back to blog

MQTT Error Codes: Meanings and Troubleshooting

Find what an MQTT error means, identify whether it comes from the broker, client library, or network, and check the right settings before retrying.

Author:
Mqttable Editorial
Published:

Find your error

You do not need to read this guide from start to finish. Match your client library or MQTT version, then jump to the code. 135 and 0x87 are the same value; PubSubClient -4 and MQTT 3.1.1 CONNACK 4 are not.

If you know the value, use your browser’s find-in-page search. For other values, use the contents to reach MQTT 5, MQTT 3.1.1, or client-library errors. The 77 entries include all 43 assigned MQTT 5 values, but are not an exhaustive catalogue of every SDK error.

Identify the failed operation

  • CONNACK

    What it tells you
    Whether the broker accepted the connection request.

  • SUBACK / UNSUBACK

    What it tells you
    Which subscription or unsubscription was accepted, in Topic Filter order.

  • PUBACK / PUBREC / PUBREL / PUBCOMP

    What it tells you
    The publication’s progress through its QoS acknowledgement exchange.

  • DISCONNECT

    What it tells you
    Why the connection is closing; also check which endpoint sent it.

  • AUTH

    What it tells you
    Authentication progress, not necessarily failure.

A failed publish or subscription acknowledgement does not by itself mean the connection closed. The same number can also have a different meaning in another packet or protocol version. MQTT 5.0 · MQTT 3.1.1

MQTT 5 reason codes

Choose the symptom group, then find the value. Each entry lists its applicable packets: a failed SUBACK or PUBACK does not by itself close the connection. This section covers 35 failure codes and 8 success or progress codes. MQTT 5.0 standard

Identity and permissions

132 (0x84): Unsupported Protocol Version

Packets: CONNACK

The endpoint does not accept the requested MQTT version. For example, the client requests 5.0 from an endpoint configured for 3.1.1 only.

  • Edit the client’s MQTT version, choose a supported version, reconnect, and inspect CONNACK in Trace.
  • Changing a TCP port alone does not change the MQTT version.

133 (0x85): Client Identifier not valid

Packets: CONNACK

The broker rejects the Client ID, for example because of its format or length. This is different from 0x8E, where a duplicate ID replaces an existing connection.

  • Edit Client ID to an accepted identifier and verify successful CONNACK in Trace.
  • A platform that binds identities to registered devices requires an authorized ID, not an arbitrary replacement.

134 (0x86): Bad User Name or Password

Packets: CONNACK

Connection authentication failed. Saved credentials may be stale, or the username and password fields may not match the platform’s required format.

  • Edit the client’s authentication details, enter valid credentials, and inspect CONNACK in Trace.
  • Verify input and credential validity; disabling certificate verification does not fix an MQTT username or password rejection.

135 (0x87): Not authorized

Packets: CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT

The current operation is not authorized. A client may connect successfully but lack permission to publish to factory/cmd. A failed PUBACK is not itself a DISCONNECT.

  • Identify the rejected operation in Trace and record its topic and identity.
  • Have the administrator check permission for that operation, then retry the same identity and topic rather than merely changing the password.

138 (0x8A): Banned

Packets: CONNACK

The server has banned the client. This is not an ordinary password typo, and repeated reconnect attempts will not lift the ban.

  • Save the rejection from Trace and give the administrator the Client ID, account, and timestamp to check ban records.
  • Retry after the restriction is resolved; do not rotate identities to evade it.

140 (0x8C): Bad authentication method

Packets: CONNACK, DISCONNECT

The authentication method is unsupported or inconsistent with the exchange. This differs from 0x86, which rejects credentials rather than the method itself.

  • Edit the client’s Authentication Method to match the broker configuration.
  • Inspect CONNECT, AUTH, and CONNACK in Trace; both the method name and its exchange must agree.

Server availability and redirection

136 (0x88): Server unavailable

Packets: CONNACK

The server answered the MQTT connection request but cannot currently provide service. Receiving CONNACK distinguishes this from a TCP connection that never succeeded.

  • Save CONNACK and its timestamp from Trace, confirm the intended environment, and check broker health.
  • Retry the same connection settings after service recovery.

137 (0x89): Server busy

Packets: CONNACK, DISCONNECT

The broker cannot currently continue processing this client’s requests. It can reject a connection or close an established one; the code does not identify the exact bottleneck.

  • Stop bulk tests or rapid publishing in Mqttable.
  • Correlate the failure time with broker resources and logs. After recovery, verify one client before gradually increasing load.

139 (0x8B): Server shutting down

Packets: DISCONNECT

The server is shutting down and closing established connections. Check for maintenance, a restart, or a node being taken out of service.

  • Correlate the DISCONNECT timestamp in Trace with maintenance records.
  • Wait for recovery or use an administrator-provided available endpoint, then verify connection and subscriptions. Do not reset credentials or Client ID for this code.

156 (0x9C): Use another server

Packets: CONNACK, DISCONNECT

The server requests a temporary switch to another server, not a permanent migration. An optional Server Reference may supply the destination.

  • Inspect Server Reference in Trace and confirm the destination with the administrator.
  • Create or select that broker endpoint in Connections, retaining the original address. Verify TLS and authentication; do not assume automatic redirection.

157 (0x9D): Server moved

Packets: CONNACK, DISCONNECT

The server requests a permanent change of server location. Unlike temporary switching with 0x9C, the saved configuration should be updated.

  • Read Server Reference in Trace or obtain the verified destination from the administrator.
  • Update the broker’s Host, Port, and required TLS settings in Connections, then verify connection, subscriptions, and received messages.

Keep Alive, sessions, and disconnection

141 (0x8D): Keep Alive timeout

Packets: DISCONNECT

The broker received no MQTT control packet from the client within 1.5 times the effective nonzero Keep Alive. A 20-second value gives 30 seconds; business messages are not the only packets that count.

  • Check the client’s Keep Alive and any Server Keep Alive in CONNACK.
  • Enable Trace → Heartbeat visibility and inspect PINGREQ/PINGRESP. Missing outbound heartbeats warrant checking sleep or blocked execution, not simply setting Keep Alive to zero.

142 (0x8E): Session taken over

Packets: DISCONNECT

Another connection used the same Client ID, causing the broker to close the old one. A debugger borrowing a device ID can create repeated takeovers when both reconnect.

  • In Connections, change the debugging client’s Client ID to a separate authorized value and stop duplicate instances.
  • Verify both distinct IDs stay connected. Toggling Clean Start does not solve concurrent identity collisions.

152 (0x98): Administrative action

Packets: DISCONNECT

An administrative action closed the connection, such as a manual disconnect or management operation. Either endpoint can send it; do not automatically blame the broker administrator.

  • Check DISCONNECT direction and timestamp in Trace, then consult that endpoint’s management logs.
  • Reconnect after the action is resolved. A recurring policy issue needs a policy fix, not faster reconnects.

160 (0xA0): Maximum connect time

Packets: DISCONNECT

The connection reached its authorized maximum lifetime, even if traffic and heartbeats remained healthy. This is neither Keep Alive timeout nor offline session expiry.

  • Compare successful connection and DISCONNECT timestamps in Trace across attempts.
  • Check the server’s connection-lifetime policy and credential lifecycle. Refresh credentials or reconnect as required rather than increasing Keep Alive blindly.

Topics, subscriptions, and supported features

143 (0x8F): Topic Filter invalid

Packets: SUBACK, UNSUBACK, DISCONNECT

The Topic Filter was rejected. The standard also uses this for a correctly formed filter that is unacceptable for this client; it is not always a wildcard syntax mistake.

  • Inspect the SUBSCRIBE or UNSUBSCRIBE filter in Trace.
  • Retry a permitted exact topic instead of a broad filter. Also check + and # placement; malformed syntax can instead produce 0x81 or 0x82.

144 (0x90): Topic Name invalid

Packets: CONNACK, PUBACK, PUBREC, DISCONNECT

The recipient rejects the Topic Name. For a publication, inspect its PUBLISH topic; for a refused connection, also inspect the CONNECT Will Topic. This is not limited to string-encoding errors.

  • In Composer, retry a permitted exact topic.
  • For CONNACK rejection, check and correct the client’s Will Topic. Compare the packets and distinguish a Topic Name from a subscription filter.

148 (0x94): Topic Alias invalid

Packets: DISCONNECT

A PUBLISH uses an invalid Topic Alias, such as alias 3 when the peer allows a maximum of 2. Explicit alias value 0 is also invalid on the wire.

  • Compare PUBLISH Topic Alias with the peer’s Topic Alias Maximum in Trace.
  • Omit the alias and retry with the full topic. The connection form’s Topic Alias Max controls aliases received by this client.

154 (0x9A): Retain not supported

Packets: CONNACK, DISCONNECT

The client requested retained-message behavior from a broker that does not support it. This can involve an ordinary retained publication or Will Retain during connection.

  • Inspect Retain Available in CONNACK.
  • Turn Composer → Retain off and retry. For connection-stage rejection, turn off the client’s Will Retain rather than only changing the publishing form.

155 (0x9B): QoS not supported

Packets: CONNACK, DISCONNECT

The requested QoS exceeds broker capabilities, such as QoS 2 publishing against a QoS 1 maximum or an unsupported Will QoS. This is different from a subscription being granted a lower QoS.

  • Inspect Maximum QoS in CONNACK.
  • Select a supported QoS in Composer and retry. For connection rejection, check Will QoS. Confirm that the lower delivery level still meets application requirements.

158 (0x9E): Shared Subscriptions not supported

Packets: SUBACK, DISCONNECT

The client requested a shared subscription such as $share/workers/lab/temp, but the broker does not support it. A successful connection does not imply shared-subscription support.

  • Check Shared Subscription Available in CONNACK.
  • Retry lab/temp in the subscription form to test an ordinary subscription. This removes shared-group distribution and is not a behaviorally equivalent production replacement.

161 (0xA1): Subscription Identifiers not supported

Packets: SUBACK, DISCONNECT

SUBSCRIBE included a Subscription Identifier that the server does not support. This labels a subscription; it is not a Client ID or Packet Identifier.

  • Clear the optional Subscription Identifier in the subscription form; do not enter 0 instead of omitting it.
  • Retry, inspect the new SUBSCRIBE in Trace, and verify successful SUBACK.

162 (0xA2): Wildcard Subscriptions not supported

Packets: SUBACK, DISCONNECT

The filter uses + or #, such as lab/+/temp or lab/#, but the server does not support wildcard subscriptions.

  • Enter an exact topic such as lab/device01/temp in the subscription form and inspect SUBACK in Trace.
  • Subscribe to required topics individually and check Wildcard Subscription Available in CONNACK.

Inflight messages, size, and quotas

145 (0x91): Packet Identifier in use

Packets: PUBACK, PUBREC, SUBACK, UNSUBACK

A new operation reused a Packet Identifier still occupied by an unfinished operation. This is not a Client ID or an application message ID; a legitimate retransmission is not automatically an error.

  • Inspect identifiers and acknowledgements for the same session and sending direction in Trace or PCAP.
  • Fix allocation or session state. Use Clean Start only when discarding previous subscriptions and pending session state is acceptable.

146 (0x92): Packet Identifier not found

Packets: PUBREL, PUBCOMP

The recipient cannot find the corresponding QoS 2 state. This can occur during recovery and does not alone prove a connection fault or a lost application message.

  • Inspect PUBLISH → PUBREC → PUBREL → PUBCOMP for the same session in Trace or PCAP.
  • Check Session Present on reconnection. Do not immediately republish and risk an application duplicate.

147 (0x93): Receive Maximum exceeded

Packets: DISCONNECT

Too many QoS 1/2 publications are in flight before the required acknowledgements complete. Receive Maximum is a concurrency window, not messages per second or payload size.

  • Compare Receive Maximum in CONNECT/CONNACK with the acknowledgement flow in Trace.
  • Reduce sender-side inflight concurrency. The client form’s Receive Max advertises its own receiving capacity, not the broker’s.

149 (0x95): Packet too large

Packets: CONNACK, DISCONNECT

The complete MQTT packet exceeds the receiver’s limit, including topic, properties, and headers. A 2,048-byte payload already exceeds a 1,024-byte packet limit before overhead is added.

  • Inspect the peer’s Maximum Packet Size in Trace.
  • In Composer, keep topic and QoS unchanged and try {"ok":1}. Then reduce the original message. Local send rejection is not proof of a broker-issued reason code.

150 (0x96): Message rate too high

Packets: DISCONNECT

The recipient considers the arrival rate too high. Short scheduling intervals or several publishers together may exceed its accepted rate. This differs from the inflight window in 0x93.

  • Stop Scheduled Messages or Bench, then test one manual publication in Composer.
  • If it succeeds, lengthen the interval or reduce concurrent publishers according to the broker’s actual rate policy.

151 (0x97): Quota exceeded

Packets: CONNACK, PUBACK, PUBREC, SUBACK, DISCONNECT

An implementation or administrative quota was exceeded, such as a subscription or message-related allowance. The code alone does not identify the quota.

  • Use Trace to identify the rejected CONNECT, PUBLISH, or SUBSCRIBE and inspect Reason String.
  • Consult broker logs, remove unneeded test resources or adjust the quota, then retry the same operation.

159 (0x9F): Connection rate exceeded

Packets: CONNACK, DISCONNECT

Too many connections are being attempted within the allowed period, for example during a reconnect surge. This is not the total concurrent-connection limit or the publish rate.

  • Stop bulk connection tests in Mqttable and check the original client for reconnect loops.
  • Verify one client first. In the application, use increasing retry delays with jitter and recover within the broker’s connection-rate policy.

Packet format and other errors

128 (0x80): Unspecified error

Packets: CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT

A connection, publication, or subscription failed without a more specific explanation. The code does not by itself establish bad credentials or broker overload.

  • Open the failed packet in Trace, check for a Reason String, and note the preceding request and timestamp.
  • Retry a minimal version of that operation and correlate it with broker logs.

129 (0x81): Malformed Packet

Packets: CONNACK, DISCONNECT

The MQTT packet has invalid encoding or structure, such as an incorrect length, fixed-header flags, or string encoding. This is different from invalid JSON inside a payload.

  • Import a decodable capture from the original device into PCAP and inspect the preceding packet.
  • Compare with the same normal operation in Connections. Fix or update the faulty packet encoder or decoder, not the reconnect interval.

130 (0x82): Protocol Error

Packets: CONNACK, DISCONNECT

The exchange violates protocol rules, for example by sending another CONNECT on an already established network connection. Parseable bytes can still be invalid in the current protocol state.

  • Inspect packet order for the same connection in Trace or PCAP.
  • Remove duplicate connection logic and retest with one client instance. A custom client needs its state machine corrected.

131 (0x83): Implementation specific error

Packets: CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT

The request is valid at the protocol level but is rejected by the recipient’s implementation. Its exact cause needs implementation-specific information.

  • Record the Reason String and request properties in Trace.
  • Remove optional properties for a controlled comparison, then provide the smallest reproducible request and broker version to its maintainer.

153 (0x99): Payload format invalid

Packets: CONNACK, PUBACK, PUBREC, DISCONNECT

The payload does not match its Payload Format Indicator, for example invalid UTF-8 bytes declared as UTF-8 text. This is not a generic JSON validation code; CONNACK rejection can concern the Will Payload.

  • Check Payload Format Indicator and actual bytes in the send workspace.
  • Correct UTF-8 text or omit the UTF-8 claim for binary data. Inspect the new response in Trace; fix the Will Payload when connecting fails.

Success and authentication progress

These 8 distinct values are outside the failure-code range starting at 0x80. The three packet-specific names for 0x00 are explained together. MQTT 5.0 §2.4

0 (0x00): Success / Normal disconnection / Granted QoS 0

Packets: CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, UNSUBACK, AUTH, DISCONNECT, SUBACK

Not an error: CONNACK accepts the connection, DISCONNECT closes it normally, and SUBACK grants QoS 0. Other acknowledgements confirm their corresponding step.

  • Check the packet type and direction in Trace.
  • For a disconnect, identify its sender. For a successful publish acknowledgement, still inspect the subscriber’s received PUBLISH before concluding that the subscriber received the message.

1 (0x01): Granted QoS 1

Packets: SUBACK

The subscription was accepted with a maximum QoS of 1. It is not a connection error, and received messages can have a lower QoS.

  • Compare SUBSCRIBE with SUBACK in Trace to identify the accepted Topic Filter.
  • Continue observing received PUBLISH packets; this code does not require a reconnect.

2 (0x02): Granted QoS 2

Packets: SUBACK

The subscription was accepted with a maximum QoS of 2. This does not certify exactly-once processing by an application database.

  • Inspect SUBACK and the actual PUBLISH QoS in Trace.
  • To verify application deduplication, also check the consumer’s processing results rather than relying only on MQTT acknowledgements.

4 (0x04): Disconnect with Will Message

Packets: DISCONNECT

The client requests disconnection and publication of its configured Will under the Will rules. This is not a credential error, and publication need not be immediate.

  • Confirm the client sent 0x04 in Trace.
  • Observe the Will Topic with a separate subscriber and check the original client’s disconnect logic and Will Delay. Do not assume the ordinary Disconnect button sends this code.

16 (0x10): No matching subscribers

Packets: PUBACK, PUBREC

The broker accepted the publication but found no matching subscribers. This is not a publish failure; the broker may return 0x00 instead.

  • Connect a second test Client ID in Connections, subscribe to the same topic, and wait for a successful SUBACK before publishing.
  • Verify the subscriber’s PUBLISH in Trace, not just a change in reason code.

17 (0x11): No subscription existed

Packets: UNSUBACK

The current session has no subscription with that Topic Filter. For example, subscribing to lab/# does not create an exact lab/temp subscription to remove.

  • Compare SUBSCRIBE and UNSUBSCRIBE in Trace and use the original complete Topic Filter.
  • Confirm the same client and session are selected. A reconnect is normally unnecessary.

24 (0x18): Continue authentication

Packets: AUTH

Enhanced authentication requires another exchange. This is neither a failure by itself nor proof that connection or publishing has been authorized.

  • Follow AUTH packets and the final outcome in Trace.
  • Match the client’s Authentication Method to the server. If progress stops, check whether the original client implements the next step of that method.

25 (0x19): Re-authenticate

Packets: AUTH

An already connected client starts re-authentication using the connection’s authentication method. This is not a server notification that the client has been disconnected.

  • Check AUTH direction and the subsequent outcome in Trace.
  • If a disconnect follows, inspect its actual failure code. Do not interpret 0x19 itself as bad credentials or an instruction to reconnect.

MQTT 3.1.1 return codes

CONNACK uses 0x00 for success and 0x01 to 0x05 for connection refusal. SUBACK uses 0x00, 0x01, and 0x02 for granted QoS, and 0x80 for failure. MQTT 3.1.1 has no server DISCONNECT reason codes equivalent to MQTT 5. MQTT 3.1.1 standard

0 (0x00): Connection accepted / Granted QoS 0

Packets: CONNACK, SUBACK

This is not an error. In CONNACK it accepts the connection; in SUBACK it grants QoS 0 for the corresponding subscription.

  • Open the packet in Connections → Trace → Grid.
  • If messages are missing, inspect SUBACK and the subscriber’s received PUBLISH. A successful connection alone does not prove delivery.

1 (0x01): Unacceptable protocol version / Granted QoS 1

Packets: CONNACK, SUBACK

In CONNACK the broker rejects the MQTT protocol version. In SUBACK the same value is successful: QoS 1 was granted.

  • Check the packet type in Trace first.
  • For CONNACK, edit the client’s MQTT version, select a version the broker supports, and reconnect. SUBACK needs no fix.

2 (0x02): Identifier rejected / Granted QoS 2

Packets: CONNACK, SUBACK

In CONNACK the Client ID is unacceptable, for example because of its length or allowed characters. In SUBACK it grants QoS 2.

  • For a rejected connection, edit Client ID to a permitted nonempty identifier and reconnect.
  • Try mqttablecheck01 only when the test account permits arbitrary IDs; never borrow a production device’s identity.

3 (0x03): Server unavailable

Packets: CONNACK

The broker received the connection request but cannot provide MQTT service. This code alone does not identify a Wi-Fi or cable failure.

  • Save CONNACK and its timestamp from Trace, then check broker health and logs.
  • Retry after service recovery instead of repeatedly pressing Connect.

4 (0x04): Bad user name or password

Packets: CONNACK

The broker rejects the supplied username or password. Check input mistakes, stale credentials, and the required credential format.

  • Edit the client’s authentication details, enter the correct credentials, and reconnect.
  • Inspect the new CONNACK in Trace. Do not disable TLS verification or expose passwords in screenshots.

5 (0x05): Not authorized

Packets: CONNACK

The server does not permit this client to connect. Correct credentials do not necessarily grant access under the account, device, or connection policy.

  • Check Username, Client ID, and the target broker in the client form.
  • Ask the administrator to check connection permissions at the failure time, then reconnect and verify CONNACK 0x00.

128 (0x80): Subscription failure

Packets: SUBACK

MQTT 3.1.1 reports subscription failure without identifying the precise reason. This is not the MQTT 5 Unspecified error, despite sharing its numeric value.

  • Match each SUBACK return value to its SUBSCRIBE Topic Filter in order in Trace.
  • Retry one permitted exact topic and have the administrator check subscription permissions.

Client-library error codes

These values are defined by client libraries. Match the library and version before interpreting a number using a protocol table.

PubSubClient: ESP32 / ESP8266

These are PubSubClient client.state() values, often printed as rc=-2 or rc=-4 in Arduino logs. They are not negative MQTT 5 reason codes, and other Arduino libraries may assign different meanings. Positive values 1 to 5 use the connection-return meanings in the MQTT 3.1.1 section. Definitions Connection implementation

PubSubClient -2: connection failed

Code / log: MQTT_CONNECT_FAILED / rc=-2

The underlying Arduino Client could not connect. Check the address, listener, network path, and any TLS wrapper before treating this as an MQTT credential rejection.

  • In Mqttable Connections, compare the same Host, Port, and transport with a separate authorized Client ID.
  • If that works, check connectivity on the ESP32/ESP8266 itself; a desktop connection does not prove the device has the same network access.

PubSubClient -4: connection timeout

Code / log: MQTT_CONNECTION_TIMEOUT / rc=-4

The client timed out. During connection establishment, this can mean CONNECT was sent but no broker response arrived in time. It is not CONNACK return code 4.

  • Compare CONNECT/CONNACK and heartbeat traffic using an authorized Proxy capture or decodable PCAP from the device.
  • Check the endpoint and whether the application services its network loop. Do not just lengthen the timeout without locating the missing response.

PubSubClient -3: connection lost

Code / log: MQTT_CONNECTION_LOST / rc=-3

A previously established connection was lost. This status does not identify whether the broker, device, or network caused the loss.

  • Keep the device log immediately before the loss and inspect its PCAP for MQTT termination or TCP closure.
  • Check for another client using the same Client ID, but confirm it with evidence rather than assuming every lost connection is a takeover.

PubSubClient -1: disconnected state

Code / log: MQTT_DISCONNECTED / rc=-1

The client is disconnected. This can be an initial or deliberately disconnected state, not a precise diagnosis of the preceding failure.

  • Record the result and state immediately after the device’s connect attempt.
  • Use Mqttable Connections for a controlled comparison; if it succeeds, inspect the application’s connection lifecycle rather than searching for a broker-side -1 reason code.

Paho Python

The entries below refer specifically to paho.mqtt.enums.MQTTErrorCode. Keep it separate from ConnackCode and ReasonCode. Paho’s VERSION2 callbacks also use ReasonCode for MQTT 3 connections, with changed nonzero numeric values; seeing 135 in a callback is not proof that the wire protocol is MQTT 5. Enums · Callback migration

Paho Python 4: client is not connected

Code / log: MQTT_ERR_NO_CONN

In the MQTTErrorCode API enum, 4 means no connection. It does not mean bad credentials as CONNACK 4 does.

  • Wait for a successful connection callback before dependent operations and handle subsequent disconnects.
  • Compare a single publish in Mqttable Connections → Composer. If that succeeds, check the Python application’s timing and connection state.

Paho Python 5: connection refused

Code / log: MQTT_ERR_CONN_REFUSED

The MQTTErrorCode enum uses 5 for a refused connection. First identify whether the number came from this enum, a legacy CONNACK callback, or a ReasonCode object.

  • Retain the Python callback name and full error, then compare CONNACK in Mqttable Trace.
  • Only diagnose an authorization rejection when the actual response supports it; do not treat every API error 5 as a password problem.

Paho Python 7: connection lost

Code / log: MQTT_ERR_CONN_LOST

MQTTErrorCode 7 reports a lost connection. There is no assigned MQTT 5 wire reason code 0x07 to look up for this API error.

  • Record Python logs, connection timing, and the last exchange.
  • Use an authorized Proxy or decodable PCAP to distinguish a broker response from a transport interruption. Check the original client’s network loop as well as server logs.

Paho Python 16: keepalive timeout

Code / log: MQTT_ERR_KEEPALIVE

MQTTErrorCode 16 identifies a keepalive failure. MQTT 5 PUBACK/PUBREC reason 16 (0x10) instead means no matching subscribers.

  • Inspect PINGREQ/PINGRESP in the original client’s traffic and ensure its network loop is being serviced.
  • Enable Trace → Heartbeat for a Mqttable comparison. Distinguish a client-detected timeout from a broker-issued 141 / 0x8D.

Paho Java

These entries refer to org.eclipse.paho.client.mqttv3.MqttException. Keep getReasonCode() together with getCause(); these five-digit values are Java-library errors, not one-byte MQTT wire codes. Exception reference · Numeric values Connection-loss report

Paho Java 32000: timed out waiting for a response

Code / log: REASON_CODE_CLIENT_TIMEOUT

The Java client timed out waiting for a response, including a keepalive response.

  • Save the exception and identify the outstanding request.
  • In a decodable PCAP or authorized Proxy trace, look for the corresponding reply. Separate a silent network path from an application that cannot process incoming traffic.

Paho Java 32100: client is already connected

Code / log: REASON_CODE_CLIENT_CONNECTED

The client is already connected. This is a local lifecycle problem, not a broker rejection code.

  • Remove duplicate connect calls and give one component ownership of reconnects.
  • A single stable Mqttable connection is a useful baseline; changing broker credentials will not fix overlapping application connect calls.

Paho Java 32103: unable to connect to server

Code / log: REASON_CODE_SERVER_CONNECT_ERROR

The Java client could not establish its server connection; inspect the nested cause for details.

  • Record getReasonCode() and getCause(), then compare the same endpoint and transport in Mqttable Connections.
  • Investigate the original host’s DNS, routing, and TLS configuration according to that cause, not the outer number alone.

Paho Java 32104: client is not connected

Code / log: REASON_CODE_CLIENT_NOT_CONNECTED

The operation requires a connected client. A previous connection may also have been lost.

  • Wait for successful asynchronous connection completion before publishing or subscribing.
  • Compare with one successful Mqttable publish, then fix the Java state transition; do not assume calling connect means an asynchronous connection has finished.

Paho Java 32109: Connection lost / java.io.EOFException

Code / log: REASON_CODE_CONNECTION_LOST

The connection ended unexpectedly. A reported form is Connection lost (32109) - java.io.EOFException; the nested exception adds context but does not identify a unique root cause.

  • Save the entire exception chain and the broker log at that time.
  • Inspect device traffic in PCAP for the last MQTT exchange and connection closure; check duplicate IDs, server restarts, and the network path against that evidence.

Paho Java 32110: connect already in progress

Code / log: REASON_CODE_CONNECT_IN_PROGRESS

Another connection attempt is already in progress on this client.

  • Serialize connection attempts and wait for their completion or failure.
  • Do not let a retry timer and automatic reconnect independently start new attempts. Use Mqttable as a single-connection baseline, not as a replacement for fixing the Java state machine.

Paho Java 32202: too many publishes in progress

Code / log: REASON_CODE_MAX_INFLIGHT

The Java client’s local inflight limit has been reached. This is not automatically a broker-issued 147 / 0x93.

  • Reduce concurrent publishes and inspect acknowledgement completion through PCAP or Proxy.
  • A single-message Mqttable test can check basic delivery. Investigate missing ACKs before increasing local inflight limits.

Qt / C-more devices

Qt MQTT defines the following four client errors; they also appear in the AutomationDirect C-more device reference. Values above 0xFF cannot fit into MQTT 5’s one-byte Reason Code field. Other clients, including Mqttable, need not display these same numbers. Reference list · Client-error definitions

Qt 256 (0x100): Transport error

Source: Client status, not an MQTT wire reason code. Code list

The client reports a transport problem or unexpected connection loss. This is not a reason code sent by the broker.

  • Use a separate test Client ID in Connections with the same endpoint and transport.
  • Compare connection errors with the original device’s logs or imported PCAP evidence to separate TCP loss from TLS handshake failure.

Qt 257 (0x101): Protocol violation

Source: Client status, not an MQTT wire reason code. Code list

The client detected a protocol violation and closed the connection. This extension code is not MQTT 5 0x81.

  • Keep the original client logs and preceding packets.
  • Inspect decodable MQTT traffic in PCAP, then compare with a normal Mqttable publish/subscribe exchange to isolate the original client, server, or intermediary.

Qt 258 (0x102): Unknown error

Source: Client status, not an MQTT wire reason code. Code list

The client could not classify the failure. The code alone cannot distinguish transport, authentication, or implementation problems.

  • Try the same broker through Connections and compare outcomes.
  • Record the original client version, full error log, and timestamp. If Mqttable cannot reproduce it, retain a capture from the original device.

Qt 259 (0x103): MQTT 5-specific error

Source: Client status, not an MQTT wire reason code. Code list

This is a wrapper indicating an MQTT 5 failure, not the final diagnosis. A separate reason code, such as 0x87, may provide the cause.

  • Inspect the original client’s detailed error properties.
  • When reproducing in Mqttable, open CONNACK, an acknowledgement, or DISCONNECT in Trace and look up its actual Reason Code in the MQTT 5 section.

ESP-IDF / ESP-TLS

On ESP32, the library matters: ESP-IDF transport errors are a separate code system from PubSubClient states. ESP-IDF error reference

ESP-IDF 32774 (0x8006): ESP-TLS connection timeout

Code / log: ESP_ERR_ESP_TLS_CONNECTION_TIMEOUT / 0x8006

ESP-IDF reports a timeout while opening the lower-level connection. The enum is not an MQTT CONNACK value and does not, by itself, prove a certificate problem.

  • Read the ESP-IDF error type and transport details together.
  • Check the device’s endpoint and network, then compare the matching transport in Mqttable Connections. Keep this code separate from PubSubClient rc=-4 even when both involve an ESP32.

Network, TLS, and WebSocket errors

The first six entries use Node.js error names, which can appear underneath MQTT applications. WebSocket 1006 belongs to a different protocol. Diagnose the reported layer before changing MQTT credentials or QoS. Node.js errors · WebSocket close codes

TCP and DNS

ECONNREFUSED: MQTT transport connection refused

Code / log: connect ECONNREFUSED

In Node.js-style errors, the target actively refused the connection. This is different from an MQTT CONNACK authorization rejection.

  • Check the broker listener, address, port, and container/network reachability.
  • In Mqttable Connections, use the same transport to compare. A desktop success does not validate the DNS or routing inside the original application’s container.

ECONNRESET: MQTT connection reset by peer

Code / log: read ECONNRESET / connection reset by peer

The underlying connection was forcibly closed. The error does not identify a particular MQTT rule violation.

  • Correlate the failure with broker and proxy logs.
  • Inspect the correct TCP flow in PCAP; if no MQTT response is visible, keep transport failure separate from MQTT rejection. A reset alone is not proof of bad credentials.

ETIMEDOUT: MQTT connection or network operation timed out

Code / log: connect ETIMEDOUT

A network operation did not complete within its timeout. It is not the MQTT 5 Keep Alive reason code.

  • Determine whether the timeout happened before MQTT CONNECT, during connection establishment, or on an existing connection.
  • Compare Connections errors and original-device PCAP evidence; check the network path before adjusting timers.

ENOTFOUND: MQTT broker hostname could not be resolved

Code / log: getaddrinfo ENOTFOUND

The client could not resolve the hostname. MQTT username, topic, and QoS changes do not repair name resolution.

  • Check the Host spelling and DNS from the original runtime.
  • Compare the same hostname in Mqttable Connections, accounting for split DNS or container differences. Do not switch permanently to an IP address if that breaks TLS hostname verification.

TLS certificate validation

CERT_HAS_EXPIRED: a certificate is past its validity period

Code / log: CERT_HAS_EXPIRED

Certificate validation reports an expired certificate. This is a TLS error, not an MQTT reason code.

  • Check the original machine’s clock and the certificate chain, then renew the expired certificate.
  • Retest TLS in Mqttable Connections with verification enabled. Disabling verification is not a production fix.

ERR_TLS_CERT_ALTNAME_INVALID: broker address and certificate do not match

Code / log: ERR_TLS_CERT_ALTNAME_INVALID

The hostname or IP does not match the certificate’s subject alternative names.

  • Use the intended broker hostname covered by its certificate, or issue a matching certificate.
  • Verify the corrected Host and TLS settings in Mqttable Connections; do not bypass hostname validation to hide the mismatch.

WebSocket

1006: abnormal closure without a Close frame

Code / log: WebSocket close code 1006

The endpoint reports abnormal closure without receiving a WebSocket Close frame. The reserved value 1006 is not sent in a Close frame and is not an MQTT reason code.

  • Check the original browser’s handshake, WS/WSS endpoint, and reverse-proxy logs.
  • Compare the same WebSocket endpoint in Mqttable Connections, then distinguish WebSocket failure from MQTT rejection; native-client success does not validate every browser policy.

Collect evidence and verify the fix

The examples in this guide use Mqttable, the MQTT workbench published by this site. You can follow the same checks in your client logs and broker logs. UI names refer to Mqttable’s English interface.

Find the original response in Trace

Find the response in Mqttable: open Connections → your Broker → Trace → Grid, clear Topic/Payload filters, select the client, and open the response. Check its type, direction, and reason. Enable Heartbeat for PING packets; a filtered-out packet is not evidence of a missing response. Trace guide

For an external device, use its logs, a decodable PCAP, or authorized traffic through Proxy. Connections Trace does not automatically observe other applications. Compare the same endpoint and transport using a separate authorized test identity; a successful desktop test does not prove the original device has identical DNS, routing, or TLS settings. These checks are diagnostic suggestions, not per-code runtime test results.

When there is no reason code

A missing MQTT reason code does not mean there was no failure. Check connection errors in Connections and the final Trace rows, then correlate device logs and PCAP evidence for TCP closure, TLS handshake failure, or network loss. An encrypted TLS capture alone does not imply that Mqttable can read the MQTT reason code inside it. PCAP boundaries

After a fix, repeat the operation that originally failed: check CONNACK for connection acceptance, SUBACK for subscription acceptance, publication acknowledgements and subscriber reception for delivery, or connection stability under the original disconnect trigger. A Connected indicator alone is not sufficient verification. Publishing and verification

What to include when asking for help

  • The client library and version, MQTT version, and complete error text.
  • The failed operation, packet type and direction, timestamp, and relevant broker log.
  • The endpoint and transport, plus whether the failure also occurs from the original device or container.

Redact passwords, tokens, private keys, and sensitive payloads before sharing logs or captures. Record what changed and whether the original operation now succeeds.

Protocol values follow the MQTT 5.0 and MQTT 3.1.1 standards. Client and network codes use the official sources linked in their sections. The steps are diagnostic suggestions, not claims that every code was reproduced in Mqttable.