Troubleshooting#

Common problems and how to resolve them. When a cause is not obvious, check the log — it has more detail than the status line.

Cannot connect to the broker#

Check, in order:

Address and port. Confirm the broker host and port. Plain MQTT is usually 1883, MQTT over TLS usually 8883.
TLS mismatch. If the broker requires TLS, enable it in the profile and use the TLS port; if it does not, make sure TLS is off. See TLS and security.
Authentication. If the broker needs credentials, set them in the profile. See Authentication.
Firewall / proxy. If your network blocks direct connections, configure a proxy.

A failed connection turns the status indicator red and shows the reason on the status line; the log shows the full error.

TLS / certificate errors#

Make sure the selected trust mode matches your broker (public CA vs. custom CA file vs. keystore).
A hostname mismatch means the certificate does not list the address you connected to. For testing only, Trust all hostnames bypasses the check — never use it in production.
For keystores, check the password, alias, and type (JKS vs. PKCS#12), and the PEM Formatted option for PEM files.

The connection keeps dropping#

If the connection is lost unexpectedly, MQTT.fx shows Broker connection lost on the status line. Enable Auto Reconnect in the profile's general options to have MQTT.fx reconnect automatically. Also check the Keep Alive Interval if the broker is closing idle connections.

"Configuration could not be loaded" / first run#

If MQTT.fx cannot read its configuration, it shows a setup dialog:

A configuration was not found — normal on first run; MQTT.fx sets up a default configuration.
A configuration was found but seems corrupt or deprecated — you can Open the configuration file to inspect it, or Create a new default configuration (this requires a restart to take effect).

The configuration file is mqttfx-config.xml in the working directory.

I subscribed to `$SYS` but see nothing#

$SYS subscriptions are disabled by default. Enable Enable subscriptions to $SYS topics in Settings, and use the Broker status tab for broker statistics. Note that not every broker publishes $SYS topics.

Performance on busy brokers#

Use a topic filter in the Namespace Explorer to limit what is displayed.
Adjust the message buffer sizes in Settings, and consider clearing the buffer on disconnect/unsubscribe.
Watch the Incoming vs Processed meter to see whether the display is keeping up.

Where are my files?#

Configuration, scripts, add-ons, and the log live in the MQTT.fx working directory — see the Appendix. The log file (mqttfx.log) is the best artifact to share when reporting a problem.