Debug Home Assistant MQTT with MQTT Viewer

Why use a dedicated MQTT client with Home Assistant?

Home Assistant's MQTT integration and the Mosquitto broker add-on do their jobs quietly in the background. That's great until something doesn't work: an entity won't appear, a sensor reads the wrong value, or an automation never triggers. The fastest way to find out why is to look at the actual messages on the broker.

A standalone MQTT client lets you watch the raw traffic Home Assistant publishes and consumes — the MQTT discovery configs that create entities, the device state topics that update them, and the command topics your automations write to. Once you can see the messages, most "it just doesn't work" problems become obvious.

How to connect MQTT Viewer to your Home Assistant broker

These steps assume you're running the official Mosquitto broker add-on inside Home Assistant. If you use an external broker, swap in its host and port.

1. Find your broker address and credentials. In Home Assistant, go to Settings → Add-ons → Mosquitto broker. The broker runs on your Home Assistant host — typically homeassistant.local or its IP address — on port 1883. The Mosquitto add-on authenticates against your Home Assistant users, so create or note a username and password to use for MQTT.
2. Install and open MQTT Viewer. Download MQTT Viewer for macOS, Windows, or Linux and open it. It's free and needs no account.
3. Add a connection to the broker. Create a new connection, set the host to your Home Assistant address and the port to 1883, enter the MQTT username and password, then connect.
4. Subscribe to the right topics. Subscribe to homeassistant/# to inspect MQTT discovery configs and device definitions, and to # to see every message moving through the broker.
5. Watch entity state update live. Open a state topic in the topic tree and watch the interactive timeline as values change. You can scrub back through the captured history to see exactly what a device published and when.
6. Publish a test payload. Publish a message to a command or state topic to confirm an automation fires or an entity reacts, then re-send it from the searchable publish history while you iterate.

What to look for in Home Assistant MQTT traffic

A few topic patterns cover most Home Assistant debugging:

• homeassistant/# — the MQTT discovery prefix. Devices publish retained config messages here that tell Home Assistant which entities to create. If an entity is missing, this is the first place to check.
• State topics — wherever a device reports its readings. Watching these on the timeline tells you whether a sensor is actually publishing, how often, and in what format.
• Availability topics — many integrations publish online / offline here. A device stuck on offline explains a lot of "unavailable" entities.

Because MQTT Viewer decodes Base64 and Hex payloads and supports free-text and pattern-based filtering, you can cut a noisy broker down to just the topics you care about and read binary payloads without copy-pasting into a decoder. For ESP-based sensors and custom firmware, see the ESP32 MQTT debugging guide.

Familiar if you've used MQTT Explorer

Many Home Assistant users know MQTT Explorer and its topic tree. MQTT Viewer works the same way, so it feels instantly familiar — and adds an interactive timeline, payload decoding, and up to 10 simultaneous connections, so your Home Assistant broker and a scratch broker can sit side by side. It's free, open-source, and runs on macOS, Windows, and Linux. See the MQTT Explorer alternative page for more, or browse the best MQTT clients overview.

Frequently asked questions

New to the terminology? The MQTT glossary explains retained messages, QoS, wildcards, and more. When you're ready, download MQTT Viewer — it's free and installs in seconds.