The Zigbee2MQTT maintainers published the 2.0 breaking changes in an announcement discussion on GitHub. Most upgrade problems reported afterwards map to one of the points below. Read them before upgrading an existing network.
What changed
| Area | Change in 2.0 | What breaks |
|---|---|---|
| Joining | "Permit join forever" removed; joining is limited to 254 seconds; the permit_join setting is gone |
setups that left the network permanently open; configs that still set permit_join |
| Adapter | zstack is no longer the default adapter |
non-TI adapters that previously worked only because detection happened to succeed |
| Home Assistant | default status topic hass/status → homeassistant/status; entity attributes removed; child locks now switches; update_state/update_available entities removed; click/action sensors removed when legacy is off |
automations and dashboards referencing removed entities or attributes |
| Settings renamed | advanced.homeassistant_discovery_topic → homeassistant.discovery_topic, whitelist → passlist, ban → blocklist |
old keys are no longer read |
| Availability | availability_timeout, availability_blocklist/passlist, legacy_availability_payload removed |
custom availability configs |
| Extensibility | external converters load automatically from data/external_converters; extensions move from data/extension to data/external_extensions |
custom converters/extensions in the old place |
Before you upgrade
-
Back up the whole
data/directory (configuration, database, coordinator backup). -
Set the adapter explicitly in
configuration.yaml(allowed values per the docs:zstack,ember,deconz,zigate,zboss):serial: port: /dev/serial/by-id/YOUR_ADAPTER_ID adapter: ember -
Turn the legacy options off on 1.x first and fix what breaks while you can still roll back. The announcement lists
homeassistant_legacy_entity_attributes: false,homeassistant_legacy_triggers: false,legacy_api: false,legacy_availability_payload: falseanddevice_options: { legacy: false }(these are already off for newer networks). -
Rename deprecated settings (discovery topic,
passlist,blocklist). -
Move external converters and extensions to the new folders.
-
Replace "permit join forever" with pairing sessions started from the frontend or via MQTT when you add a device.
After upgrading, check the log for configuration warnings and look for unavailable entities in Home Assistant before assuming devices broke.