ESP32 MQTT debugging that shows exactly what your device publishes

When an ESP32 or ESP8266 sketch goes quiet, the fastest way to find out why is to watch the broker. MQTT Viewer shows every message the device sends in a live topic tree and timeline, and publishes test messages back.

Why use a desktop MQTT client to debug an ESP32?

Most ESP32 MQTT bugs come down to three questions. Is the device connecting to the broker? Is it publishing to the topic you think it is? Is the payload the shape your backend expects? Serial logs only show the device's side. An MQTT client on the same broker shows what was actually delivered.

MQTT Viewer keeps a live topic tree of everything on the broker, a message timeline you can scrub through, and decoders for common payload formats.

How to debug ESP32 MQTT messages with MQTT Viewer

  1. Install MQTT Viewer from the download page.
  2. Connect to the same broker your ESP32 uses. Use the exact host, port (1883 for TCP, 8883 for TLS) and credentials your firmware uses. If the device uses WiFiClientSecure over 8883, connect over TLS too.
  3. Subscribe to #. This shows every topic on the broker. Once you see traffic, narrow to a prefix like devices/esp32-1/#.
  4. Watch the device publish. Trigger the firmware and watch new topics appear in the tree and on the timeline.
  5. Decode payloads and filter. JSON reads directly. For raw bytes, switch the decoder to Hex or Base64. Filter the tree to isolate one device or value.
  6. Publish a test message back. Publish to the topic the ESP32 subscribes to and confirm it reacts. Publish history keeps the command for resending.

Reading binary and structured payloads

MQTT Viewer decodes Base64 and Hex so you can see the exact bytes PubSubClient.publish() put on the wire, and Sparkplug B if a gateway speaks it. For a one-off check, paste the bytes into the browser payload decoder.

With up to 10 connections, a development broker and a production broker can be watched at the same time. The MQTT glossary covers retained messages, QoS and wildcards.

Common ESP32 and ESP8266 MQTT problems

  • Nothing appears under #. The device is not reaching the broker. Check the host, port, credentials and WiFi.
  • Messages appear on the wrong topic. A typo or mismatched prefix between firmware and backend.
  • Payload looks like garbage. Binary where the consumer expects text, or vice versa. Switch the decoder to Hex.
  • The device never receives commands. Its subscription does not match the published topic. Publish a test message to confirm the exact topic.

Frequently asked questions

Why aren't ESP32 MQTT messages showing up?

The most common cause is a different broker, or a topic that does not match what the device publishes. Subscribe to # to confirm the device is connected at all, and check the host, port and credentials match the firmware.

What port should be used to connect to an ESP32's broker?

1883 for plain TCP or 8883 for TLS, matching what the firmware uses. If the ESP32 connects with WiFiClientSecure on 8883, MQTT Viewer must also connect over TLS.

Can MQTT Viewer send a test message to an ESP32?

Publish to the topic the device subscribes to, with the payload the firmware expects, and watch it react.

Download MQTT Viewer for macOS, Windows or Linux.

MQTT Viewer is free and open source, and runs on macOS, Windows and Linux.

Download MQTT Viewer