How to Fix an MQTT Client Reconnect Loop

Back to Blog

First Checks: Read the Broker's Side of the Story

The broker log is the fastest diagnostic in MQTT, because the broker knows why it dropped the client even when the client does not. Look for the disconnect reason attached to each drop: a takeover by another connection with the same client ID, a keep-alive expiry, or an authorization failure each read differently in the log. MQTT version matters here too - newer protocol revisions return an explicit reason code to the client on disconnect, while older ones often just close the socket, which is why the client-side log alone can be so unhelpful.

The rhythm of the loop is the second free clue. A metronomic connect-drop cycle with a fixed period suggests two clients taking the session from each other or a keep-alive expiring on schedule. Drops correlated with data bursts suggest payload or authorization problems on publish. Drops correlated with time of day or link quality point below MQTT at the network. Ten minutes of watching timestamps narrows the cause list before any configuration is touched.

Duplicate Client IDs: The Takeover Fight

The client ID uniquely identifies a session to the broker, and the specification is explicit about collisions: when a connect arrives bearing the same client ID as an existing connection, the broker must disconnect the existing one and accept the new. Two devices configured with the same ID therefore fight endlessly - each connection kicks the other off, the loser reconnects, and the loop runs at the speed of their retry timers. From the broker's perspective this is correct behavior, not an error, which is why nothing looks broken except the flapping itself.

This happens in real fleets more than it should because client IDs get copy-pasted: a cloned gateway configuration, a device template rolled out without templating the ID, a test laptop running the same config as the field unit. The fix is guaranteeing uniqueness, usually by deriving the client ID from a serial number or MAC address rather than typing it. The tell in the broker log is the takeover disconnect reason on one connection at the exact moment the other connects - once you see that pairing, the diagnosis is certain.

Keep-Alive, Middleboxes, and Auth Rejections

The keep-alive is a promise from client to broker: I will send something at least this often, and a ping if I have no data. The broker enforces it with half again as much patience - hearing nothing within one and a half keep-alive intervals, it closes the connection and publishes the client's last will. A keep-alive tuned on the bench can be too tight for a congested cellular link where packets stall, so the broker repeatedly declares the client dead mid-stall. The reverse failure also exists: a keep-alive so long that NAT gateways and firewalls along the path expire the idle connection first, and nobody notices until the next publish fails. The working range is bounded on both sides, and the right value sits above the link's normal stall length and below the shortest idle timeout in the path.

Authentication loops look like connection loops but live one layer up. The broker accepts the TCP or TLS connection, reads the connect packet, and rejects it - bad username or password, an unauthorized client identity, or a certificate problem on TLS-secured listeners. Simple clients treat this like any other failure and retry immediately, producing a tight loop that can even look like a broker attack in the logs. Related is the ACL variant: the client connects fine, publishes to a topic it lacks permission for, and brokers configured to disconnect on ACL violation drop it, so the loop cycles on every publish attempt. Both variants are visible unambiguously in the broker log, which is why the first-check step earns its place.

When to Escalate

If IDs are proven unique, keep-alive is sized to the real link, credentials and ACLs check out, and the loop persists, capture one full cycle: a packet trace on the client side plus the broker log for the same interval. That pair distinguishes the remaining suspects - a broker resource limit, a TLS renegotiation problem, a client library bug in ping handling - and is what a broker vendor or library maintainer will ask for anyway. Reconnect storms from many clients at once deserve special mention: after a broker restart, thousands of clients reconnecting simultaneously can overload it into dropping them again, which is why well-behaved clients add randomized backoff to their retry timers.

Flapping matters beyond the noise because each abnormal drop fires the client's last-will message, and every subscriber sees the device wink offline and online. For a SCADA platform such as Merobix consuming MQTT data, a flapping client means status churn and gaps, so the platform-side view of connection stability is itself a useful escalation artifact: it shows exactly when the churn started, which often lines up with a configuration deployment or a network change someone can name.

Frequently Asked Questions