# Zigbee2MQTT 2.x: Home Assistant Discovery Not Working – Solution

Configuration
1

Platform: Zigbee2MQTT 2.x, Home Assistant OS (HAOS), Mosquitto Broker
Symptom: Zigbee devices do not appear in Home Assistant, even though Zigbee2MQTT is running and connected to the MQTT broker.

Setup Used

This solution was developed and tested with the following distributed infrastructure:

  • Home Assistant OS runs as a Proxmox VM, including the Mosquitto Broker Add-on as the MQTT broker.
  • Zigbee2MQTT 2.x runs on a separate Raspberry Pi (hostname: zigbeehub), using a Sonoff Zigbee 3.0 USB Dongle Plus as the coordinator via USB.
  • Z2M connects over the network to the Mosquitto broker on the HA VM.
  • Home Assistant receives Zigbee device data exclusively via MQTT Discovery – there is no direct connection between HA and the Raspberry Pi.

This architecture is a common and recommended approach, as the Zigbee coordinator can be placed physically closer to the Zigbee devices while HA runs centrally on a server.

Raspberry Pi (zigbeehub)
  └── Zigbee2MQTT 2.x + Sonoff USB Dongle
        ↕ MQTT over network (Port 1883)
Proxmox VM
  └── Home Assistant OS
        └── Mosquitto Broker Add-on
              ↕ MQTT Discovery (homeassistant/#)
              └── Home Assistant Entities

Problem

After upgrading to Zigbee2MQTT 2.x (tested with 2.9.2), automatic Home Assistant Discovery no longer works, even though the configuration.yaml contains:

homeassistant:
  discovery: true

In older versions, discovery: true was sufficient. In Z2M 2.x a breaking change was introduced: the integration now needs to be explicitly enabled.

Root Cause

In Z2M 2.x, a new parameter enabled was added to the homeassistant block, which defaults to false. Without enabled: true, the Discovery functionality will not start, even if discovery: true is set.

This can be confirmed in the debug logs:

"homeassistant":{"discovery":true,...,"enabled":false,...}

Additionally, in this specific case there was a typo in the discovery_topic:

discovery_topic: homeassist   # ← wrong, "ant" was missing

This also prevented correct communication between Z2M and HA.

Diagnosis

1. Check Z2M logs for MQTT connection

sudo journalctl -u zigbee2mqtt -f --no-pager

Expected output when the connection is working:

Connected to MQTT server
MQTT publish: topic 'zigbee2mqtt/bridge/state', payload '{"state":"online"}'

2. Check whether Discovery messages are being sent

mosquitto_sub -h <HA-IP> -u <mqtt_user> -P <password> -t 'homeassistant/#' -v

If only homeassistant/status online appears and no other topics, Discovery is not active.

3. Enable debug logging and check the config

# Temporarily set in configuration.yaml:
advanced:
  log_level: debug

Look for the following in the logs:

"homeassistant":{"enabled":false,...}

→ If enabled: false, that is the root cause.

Solution

Full homeassistant configuration for Z2M 2.x:

homeassistant:
  enabled: true          # ← NEW in 2.x, must be set explicitly!
  discovery: true
  discovery_topic: homeassistant
  status_topic: homeassistant/status
  legacy_entity_attributes: false
  legacy_triggers: false

Complete working configuration.yaml (example):

version: 5
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://192.168.x.x:1883
  user: mqtt_user
  password: your_password
  version: 4
homeassistant:
  enabled: true
  discovery: true
  discovery_topic: homeassistant
  status_topic: homeassistant/status
  legacy_entity_attributes: false
  legacy_triggers: false
serial:
  port: /dev/ttyUSB0
  adapter: zstack
  baudrate: 115200
  rtscts: false
advanced:
  log_level: info
  log_output:
    - console
frontend:
  enabled: true
  port: 8080

Restart Z2M:

sudo systemctl restart zigbee2mqtt
sudo journalctl -u zigbee2mqtt -f --no-pager

On successful configuration, the following will appear in the logs:

Discovering entities to Home Assistant in 5s
MQTT publish: topic 'homeassistant/switch/0x.../switch/config'
MQTT publish: topic 'homeassistant/sensor/0x.../linkquality/config'

Home Assistant MQTT Integration

For HA to process the Discovery messages, the Birth Message must be correctly configured in the MQTT integration:

Settings → Devices & Services → MQTT → Gear icon → MQTT Options:

Setting Value
Enable discovery :white_check_mark: On
Discovery prefix homeassistant
Enable birth message :white_check_mark: On
Birth message topic homeassistant/status
Birth message payload online

When HA starts, it automatically publishes homeassistant/status = online, which triggers Z2M to publish all Discovery messages.

Checklist

  • homeassistant.enabled: true set in Z2M configuration.yaml
  • homeassistant.discovery_topic: homeassistant spelled correctly (no typos!)
  • homeassistant.status_topic: homeassistant/status set
  • Mosquitto Birth Message configured with topic homeassistant/status and payload online
  • Z2M restarted after configuration changes
  • Devices visible in HA under Settings → Devices & Services → MQTT

Affected Versions

Software Version
Zigbee2MQTT 2.x (breaking change vs. 1.x)
Home Assistant OS All current versions
Mosquitto Broker As HAOS Add-on

Created April 2026 · Based on hands-on troubleshooting · Zigbee2MQTT 2.9.2 + HAOS

3