Home Assistant does not show my MQTT device: discovery topic and payload

The integration must be connected to the same broker, and the discovery message must be valid JSON on the right topic.

What the message means

Discovery needs a message on the homeassistant topic prefix that names the entity. A typo in the topic or a broken payload makes the device invisible.

Fix it in this order

1. Check the MQTT integration is connected to the same broker as your device.
2. Publish the discovery payload to a topic that starts with the discovery prefix, usually homeassistant.
3. Validate the JSON, and include a unique ID and the state topic.
4. Publish the message with the retain flag so it survives restarts.
5. Watch the topic with a client such as MQTT Explorer to see what arrives.
6. Check the Home Assistant log for discovery errors.

Why it happens

Home Assistant builds an entity from a configuration message it sees on the discovery topic. The documented topic pattern is the discovery prefix, then the component, an optional node ID, the object ID and a final config segment, and the best practice for an entity with a unique_id is to use the unique_id as the object ID and leave out the node ID.

If the topic does not follow that pattern, or the JSON is invalid, nothing is created and no error appears on the device. A message published before Home Assistant was listening is lost unless it was retained; community guides and ESPHome recommend retaining discovery messages so entities come back after a restart.

If you see this, do this

Related

broker refuses clients, MQTT on the ESP32.

Last reviewed: November 2026. These are the usual causes and the order that finds them fastest. Test on your own board; clones and cables differ.

Why this happens

Home Assistant does not scan for devices. It listens to the MQTT broker and builds an entity only when it receives a configuration message on a topic that matches the discovery pattern. The pattern is the discovery prefix, the component type (such as sensor or switch), an optional node ID, an object ID and the word config. If any part is wrong, the message is simply treated as ordinary data and ignored.

The payload matters as much as the topic. It must be valid JSON, and for most components it needs at least a name, a state topic and ideally a unique_id. If the JSON is malformed, a quote is a typographic one, or a trailing comma sneaks in, the entity is dropped, and nothing is shown on the device side to tell you.

How to confirm the cause

• Subscribe to the discovery prefix from another client, for example MQTT Explorer or mosquitto_sub, and confirm your device’s message really arrives with the retain flag set.
• Copy the payload into a JSON validator. A single missing quote is enough to break it.
• In Home Assistant open the MQTT integration, choose to listen to a topic, enter homeassistant/# and publish again. If nothing appears, the message is not reaching this broker.
• Check that discovery is enabled in the MQTT integration options and that the prefix there matches the one you publish to.
• Read the Home Assistant log for lines mentioning the topic; invalid configurations are usually reported there.

Worked example

A minimal temperature sensor announcement, sent from a PC to test the setup. The topic ends in config and the message is retained:

mosquitto_pub -h 192.168.1.10 -r \
  -t homeassistant/sensor/room_temp_01/config \
  -m '{"name":"Room temperature","unique_id":"room_temp_01",
  "state_topic":"room/temp","unit_of_measurement":"C",
  "device_class":"temperature"}'

mosquitto_pub -h 192.168.1.10 -t room/temp -m 27.5

Common mistakes

• Publishing the config without the retain flag and then restarting Home Assistant.
• Putting the state data on the discovery topic itself instead of the state_topic.
• Sending a state payload that is JSON when no value_template is set, so the entity shows unknown.
• Reusing the same unique_id for two devices, which makes the second one vanish.
• Using a client library whose buffer is too small for the config message, so it is cut short and not valid JSON.

If this did not fix it

• The device and Home Assistant use different brokers or different ports, so they never meet.
• Broker access rules stop one client from publishing to the discovery prefix.
• An old retained config under a different topic is still present; clear it by publishing an empty retained message to that topic.