Input validation
Catches an empty host, an out-of-range port or a malformed URI before anything touches the network.
Feature
Connection Doctor
Most MQTT clients report “connection failed” and stop there. Connection Doctor walks the connection one stage at a time and names the step that broke, with a plain-language cause and a suggested fix.
Why a connection fails, in plain language
A broker that won't connect can fail in a dozen places: DNS, the TCP socket, the TLS handshake (including the WS/WSS upgrade), the certificate, ALPN/SNI negotiation, or the MQTT protocol itself. Connection Doctor checks each one in order and stops at the first problem, so you fix the real cause instead of poking at settings.
Every result carries the technical detail and a concrete next step. Secrets, raw payloads and private hostnames never reach the log, so a result is safe to read on a shared screen. The Pro unlock adds a shareable report with stage names and statuses only, ready for a bug report.
The stages
Checked in order, stops at the first failure
DNS resolution
Resolves the broker hostname to an address and shows the resolved IPs, so a typo or a missing record is obvious.
TCP connection
Opens the socket. Distinguishes a connection refused, a timeout and an unreachable network.
TLS handshake
Opens the encrypted channel (including the WS/WSS upgrade for WebSocket brokers). Flags an unsupported TLS version, a proxy or upgrade problem, or an ALPN/SNI mismatch.
Certificate
Validates the certificate: expiry, the SAN/CN hostname and the trust chain. Flags an expired certificate or a hostname mismatch.
ALPN / SNI
Checks the negotiated protocol and server name, for example AWS IoT's x-amzn-mqtt-ca, so a wrong ALPN protocol reads in plain language.
MQTT CONNECT
Reads the CONNACK reason code, so a bad protocol version, an auth failure or a packet-size violation reads in plain language.
Connection Doctor FAQ
What does Connection Doctor do?
It runs the connection one stage at a time (Input → DNS → TCP → TLS → certificate → ALPN/SNI → MQTT CONNECT → auth) and stops at the first failure, telling you which stage broke, the technical detail, and a suggested fix.
Is Connection Doctor free?
Yes. The free app runs the Doctor and always shows the stage that failed, with the cause and a suggested fix, TLS stages included. The one-time Pro unlock lists every TLS check as its own line (handshake, chain, expiry, hostname, ALPN/SNI) and adds a report you can share.
Do the diagnostics leak secrets?
No. Passwords, certificate material, raw payloads and private endpoint hostnames never reach the diagnostic log. The shareable report in Pro lists stage names and statuses only, so you can send it to a colleague or paste it into a ticket as is.
Does it help with TLS and mTLS errors?
That's its strongest area. It names expired certificate chains, hostname mismatches, wrong ALPN protocols (for example AWS IoT's x-amzn-mqtt-ca) and unsupported TLS versions instead of a generic “handshake failed.”
Will it explain an authentication failure?
Yes. It decodes MQTT 5 reason codes from the CONNACK packet, so you read “not authorized” or “bad username or password” instead of an opaque code.
Debug your next MQTT connection
Connection Doctor ships in MQTT Commander for iPhone and iPad.
Free · Pro unlock $4.99, one-time