Aujourd’hui, je vous propose un guide pour déboguer Zigbee2MQTT en cas de plantages récurrents. J’ai récemment eu mon Z2M qui s’est mis à planter de manière aléatoire. Vous avez peut-être déjà vécu ce problème ou l’avez même actuellement et recherchez la solution.
Le symptôme est simple : Vous utilisez Zigbee2MQTT avec un contrôleur type SLZB-xx ou une clé EFR32 et votre service plante systématiquement au démarrage avec des erreurs du type ASH_NCP_FATAL_ERROR ou HOST_FATAL_ERROR ?

Vous n’êtes pas seul ! Ce problème est souvent lié à une commande “toxique” dans la pile Zigbee qui fait saturer le réseau et le rend instable. mais il peut être résolu sans tout réinstaller. Voici comment diagnostiquer et nettoyer votre installation pour retrouver la stabilité.
Comprendre les symptômes
Le plus simple pour analyser et comprendre est d’analyser les logs. Que vous soyez sous le plug-in embarqué dans Home Assistant (onglet journal de l’app) ou sous un conteneur LXC Proxmox (console), il est simple de parcourir les logs. Bien que ce soit plus simple sous un Z2M embarqué dans Home Assistan, sur une VM Proxmox c’est à peine plus complexe. Vous n’avez qu’à connaître quelques commandes de base :
#1 se rendre dans le repertoire de configuration:
cd /opt/zigbee2mqtt/data
#2 editer le fichier de configuration:
nano configuration.yaml
#3 demarrer Z2M pour voir ce qui se passe:
npm start
Le crash se manifeste souvent par :
- Un arrêt immédiat du service : Le log indique
Adapter disconnected, stopping. - Une erreur
SEND_UNICAST: Vos logs affichentFatal error, status=HOST_FATAL_ERROR. Last Frame: [FRAME: ID=52:"SEND_UNICAST"]. - une instabilité liée au démarrage : Zigbee2MQTT semble démarrer, mais s’écroule dès qu’il tente de configurer un périphérique spécifique.
C’est même souvent une combinaison de tout en même temps qui se résume par un réseau Zigbee saturé qui finit par se réinitialiser ou rendre sourds plusieurs périphériques du réseau. Tout ce que l’on ne veut pas…
La cause racine
Un périphérique, souvent un module routeur qui sert de passerelle à plusieurs autres périphériques (comme les modules routeurs Sonoff, Lidl ou Nous), répond par un UNSUPPORTED_ATTRIBUTE à une commande de configuration. La pile zigbee-herdsman (plus stricte dans les versions récentes) panique, fait planter la puce radio et provoque un RESET_SOFTWARE de l’adaptateur. Dans le meilleur des cas, le réseau redémarre, mais reste souvent très instable tant que le problème n’est pas résolu.
Le diagnostic : Isoler le coupable
Avant toute manipulation, procédez à une sauvegarde. Si c’est une installation dans Home Assistant, procédez à une sauvegarde HA. Si c’est sous Proxmox, faites un snapshot du conteneur LXC. Je vous recommande également de faire des sauvegardes des fichiers de configuration ainsi que de la base de données de Zigbee2MQTT.
Ensuite, identifiez l’appareil fautif en parcourant vos logs ou simplement en demarrant Zigbee2MQTT pour voir ce qui se passe clairement :
- Regardez la ligne juste avant le
Fatal error. - Repérez l’adresse IEEE (ex:
0x7cc6b6fffe8b5bf1) qui précède le message d’erreur. - Si le log mentionne
Failed to configure 'Nom_de_votre_appareil', vous tenez le coupable.

Guide de résolution : Le nettoyage en 3 étapes
Étape 1 : Mettre à jour votre matériel
Les puces Zigbee EFR32 ont beaucoup évolué. La gamme de contrôleur SMLIGHT evolue egalement rapidement, il y a souvent des version beta, assurez-vous de disposer de la dernière version stable disponible aussi bien pour le firmware Zigbee (1) que pour le firmware du contrôleur lui-même (2). Une version de firmware trop ancienne est souvent incompatible avec les dernières versions de zigbee-herdsman.

Pour cela accédez à l’interface web de votre contrôleur SLZB-XX et effectuez la mise à jour du firmware Zigbee vers la version la plus récente (recherchez les versions 7.x ou 9.x). Procedez de même pour le contrôleur. Attention ne passez pas sur les version beta ! Assurez-vous de bien utiliser la dernière version stable disponible pour de la prod. Les versions bêta sont bien dans des environnements de test uniquement.
Étape 2 : Nettoyer la base de données (database.db)
Si l’appareil continue de poser problème, vous devez supprimer sa configuration corrompue.
- Arrêtez le service Z2M.
- Faites une sauvegarde de votre fichier
database.db.
# 1. Aller dans le dossier data
cd /chemin/vers/ton/repertoire/zigbee2mqtt/data/
# 2. Créer un dossier de sauvegarde
mkdir -p ./backup
# 3. Copier les fichiers vitaux dedans
cp database.db configuration.yaml state.json cache.json ./backup/
- Ouvrez-la base de donnée avec
nanoet recherchez l’adresse IEEE fautive. - Supprimez la ligne complète correspondante.
- Supprimez le fichier
state.json(il sera recréé automatiquement).
# 1. Editer la base de donnée
nano database.db
# 2. Rechercher le périphérique par son ID
grep "0x7cc6b6fffe8b5bf1" database.db
# 3. Se positionner sur la ligne du périphérique à l'aide des flèches puis couper la ligne
Ctrl + K
Attention à ne pas laisser de ligne vide dans la base de donnée, cela pourrait la corrompre. Enfin il ne reste plus qu’a enregistrer et quitter le fichier.
Ctrl + X puis Entrée
Étape 3 : Purger le broker MQTT
C’est l’étape qui est souvent oubliée. Les messages persistants peuvent forcer Z2M à reconfigurer l’appareil dès le redémarrage, ce que l’on ne veut pas puisque l’on vient de le supprimer de la base de données. Pour faire propre et ne pas surcharger inutilément MQTT, il faut donc aller le supprimer dans la base MQTT également.
- Utilisez un logiciel comme MQTT Explorer.
- Connectez-vous à votre broker.
- Supprimez les topics
homeassistant/switch/ADRESSE_IEEE/etzigbee2mqtt/NOM_APPAREIL/associés au périphérique fautif.

Désactiver la configuration automatique
Pour éviter qu’un appareil ne fasse planter votre adaptateur lors d’un futur redémarrage, vous pouvez aussi interdire à Zigbee2MQTT de le configurer automatiquement. Dans votre configuration.yaml :
devices:
'0x7cc6b6fffe8b5bf1': # Remplacez par l'IEEE de l'appareil
friendly_name: 'Mon_Appareil_Rebelle'
configure: false
Cela empêche Z2M d’envoyer les requêtes read qui provoquent l’erreur UNSUPPORTED_ATTRIBUTE.
Conclusion
Un plantage au démarrage de Zigbee2MQTT n’est pas inévitable. En examinant les journaux, en isolant le périphérique défaillant, en effaçant les fichiers de cache et en maintenant vos firmwares à jour, vous obtiendrez un réseau Zigbee stable et réactif, qui ne plantera plus et garantira un fonctionnement optimal de votre domotique. Vous savez désormais quoi faire si vos périphériques Zigbee présentent de la latence, fonctionnent de manière aléatoire ou ne sont plus visibles.
Maintenant vous savez quoi faire. Conserver ce guide de côté pour vous sortir de cette mauvaise passe le jour J !







