Koenkk
Battery Device Availability Messages Not Republished After MQTT Retained Message Loss
What happened?
After clearing retained MQTT messages from my broker (during routine maintenance), Z2M stopped publishing availability messages for battery-powered devices. Home Assistant now permanently shows these devices as "Unavailable" even though they're actively communicating (41,000+ messages sent over subsequent weeks).
Mains-powered devices (IKEA plugs) recovered immediately and had their availability messages republished automatically. Battery devices (Sonoff TRVZBs) never recovered.
The devices work perfectly from Z2M's perspective - they show as "Online" in the Z2M UI and continue sending state updates to zigbee2mqtt/<device> topics. However, the zigbee2mqtt/<device>/availability topics are never republished after being lost.
I tried multiple troubleshooting steps including restarting Home Assistant, toggling Home Assistant Discovery off/on in Z2M (which successfully republished discovery configs but not availability messages), deleting and rediscovering devices in HA, and reconfiguring devices in Z2M. None of these resolved the issue.
What did you expect to happen?
I expected Z2M to republish availability messages for battery devices when they communicate, or at least when I toggled Home Assistant Discovery off/on (which successfully republished all the discovery configs).
Availability messages shouldn't rely solely on retained MQTT messages from initial pairing - they should be refreshed periodically or when devices communicate, similar to how mains-powered devices have their availability constantly refreshed via active polling.
How to reproduce it (minimal and precise)
- Pair a battery-powered Zigbee device (e.g., Sonoff TRVZB) with Z2M
- Verify it appears as "Available" in Home Assistant
- Verify availability topic exists:
mosquitto_sub -h <broker> -t "zigbee2mqtt/<device>/availability" -v - Clear all retained messages from MQTT broker:
mosquitto_pub -h <broker> -t "#" -r -n(or restart broker without persistence) - Observe device state in HA changes to "Unavailable"
- Wait for device to send multiple messages (visible in Z2M logs and
zigbee2mqtt/<device>topic) - Check availability topic again - it will not exist/not be republished
- Try toggling Home Assistant Discovery off/on in Z2M settings - discovery configs republish but availability messages still don't
Note: Mains-powered devices recover automatically. Only battery devices are affected.
Zigbee2MQTT version
2.7.1
Adapter firmware version
20210708
Adapter
Sonoff Zigbee 3.0 USB Dongle Plus
Setup
Running Z2M in Docker on Raspberry Pi 4 (8GB) MQTT broker: Mosquitto
uname -a output: Linux z2m 6.12.47+rpt-rpi-v8 #1 SMP PREEMPT Debian 1:6.12.47-1+rpt1 (2025-09-16) aarch64 GNU/Linux
Device database.db entry
No response
Debug log
Not applicable - Z2M logs show no errors. Devices appear to function normally from Z2M's perspective and show as "Online" in the Z2M UI throughout. The issue is that availability messages simply aren't being published to MQTT after initial pairing.
Relevant info from bridge/health showing active communication: "0x842712fffe80da5d": {"messages": 41213, "messages_per_sec": 0.0162} "0x842712fffe186e14": {"messages": 41926, "messages_per_sec": 0.0165} "0x0cae5ffffeb3ddbd": {"messages": 33739, "messages_per_sec": 0.0133}
Z2M availability config: "availability": { "active": {"timeout": 10, "backoff": true, ...}, "enabled": true, "passive": {"timeout": 1500} }
Notes
Workaround: Disable availability per-device in configuration.yaml:
devices:
'<ieee_address>':
friendly_name: '
This makes Z2M republish discovery configs without availability requirements.
The root issue appears to be that availability messages for battery devices are only published once during initial pairing, unlike mains-powered devices which have their availability constantly refreshed via active polling. This makes the system fragile to any scenario where MQTT retained messages are lost, including: broker crashes, migrations, backups/restores without retained messages, or routine maintenance operations.
Per-device availability settings are also not exposed in the UI, requiring manual YAML editing.
Please note: this bug report was co-authored with AI, following a long debugging session.
