Failed to start zigbee-herdsman : résoudre l’erreur Zigbee2MQTT

L’erreur « Failed to start zigbee-herdsman » indique que Zigbee2MQTT n’arrive pas à initialiser le coordinateur Zigbee. Les causes les plus fréquentes sont un mauvais port série, un adaptateur déjà utilisé par ZHA, un type d’adaptateur incorrect, des permissions insuffisantes ou un firmware inadapté. Commencez par lire les lignes qui suivent immédiatement l’erreur : elles donnent généralement la vraie cause.

• Ne réinitialisez pas votre réseau Zigbee immédiatement.
• Sauvegardez la configuration et le répertoire de données avant toute modification.
• Utilisez de préférence le chemin stable /dev/serial/by-id/….
• Un même coordinateur ne peut pas être utilisé simultanément par ZHA et Zigbee2MQTT.
• Après chaque correction, redémarrez Zigbee2MQTT et relisez le nouveau journal.

Étape 1 : identifier le message précis

« Failed to start zigbee-herdsman » est une erreur générique. Dans Home Assistant, ouvrez le journal du module complémentaire Zigbee2MQTT et recherchez les messages juste avant ou après cette ligne : No valid USB adapter found, Cannot lock port, SRSP - SYS - ping, HOST_FATAL_ERROR ou configuration-adapter mismatch.

Si le journal est insuffisant, activez temporairement le niveau de débogage dans la configuration Zigbee2MQTT :

advanced:
  log_level: debug

Vérifier le port série du coordinateur

Après une mise à jour, un redémarrage ou le branchement d’un autre périphérique USB, un chemin comme /dev/ttyUSB0 peut changer. Utilisez si possible l’identifiant permanent proposé par Home Assistant ou le système :

serial:
  port: /dev/serial/by-id/usb-votre_coordinateur
  adapter: zstack

La valeur adapter dépend du chipset et du firmware : zstack pour de nombreux coordinateurs Texas Instruments, ember pour des modèles Silicon Labs récents, ou une autre valeur indiquée dans la documentation de l’adaptateur. Ne recopiez pas une configuration trouvée pour un autre dongle.

En tant que Partenaire Amazon, nous réalisons un bénéfice sur les achats remplissant les conditions requises. Les prix et disponibilités peuvent évoluer après leur constat. Données produit fournies temporairement par DataForSEO et conservées dans le catalogue de secours.

Désactiver le conflit avec ZHA

Si l’intégration Zigbee Home Automation (ZHA) utilise déjà le même dongle, Zigbee2MQTT ne pourra pas verrouiller le port. Dans Home Assistant, vérifiez les intégrations et désactivez ou supprimez l’utilisation du coordinateur par ZHA avant de redémarrer Zigbee2MQTT. Ne supprimez pas ZHA si elle pilote un autre coordinateur.

Corriger « Cannot lock port » ou « Resource temporarily unavailable »

Ces messages indiquent généralement que le port est occupé. Arrêtez les autres logiciels susceptibles d’utiliser le coordinateur : ZHA, une deuxième instance de Zigbee2MQTT, un conteneur ancien ou un service de détection série. Redémarrez ensuite proprement le module complémentaire.

Corriger « No valid USB adapter found »

1. Vérifiez que le dongle apparaît dans le matériel Home Assistant.
2. Débranchez-le, attendez quelques secondes et rebranchez-le.
3. Sélectionnez son chemin /dev/serial/by-id/….
4. Renseignez explicitement le bon type d’adaptateur.
5. Vérifiez que le périphérique est bien transmis à la machine virtuelle ou au conteneur.

Corriger « SRSP – SYS – ping » ou « HOST_FATAL_ERROR »

Selon la documentation Zigbee2MQTT, ces erreurs peuvent venir d’un port modifié, d’un ancien coordinateur CC2530/CC2531 instable, d’un paramètre manquant, d’un conflit avec ZHA, d’un firmware routeur installé à la place d’un firmware coordinateur ou d’un adaptateur réseau inaccessible.

• Confirmez le modèle exact et le firmware du coordinateur.
• Utilisez une rallonge USB de qualité pour éloigner le dongle des interférences USB 3 et du Wi-Fi 2,4 GHz.
• Vérifiez l’alimentation du Raspberry Pi ou de l’hôte.
• Pour un coordinateur Ethernet/PoE, contrôlez son adresse et sa disponibilité réseau.
• Ne reflashez le firmware qu’après sauvegarde et vérification de sa compatibilité.

Vérifier les permissions sous Linux

Sur une installation Linux autonome, l’utilisateur qui exécute Zigbee2MQTT doit pouvoir écrire sur le port série. La documentation propose ce test :

test -w /dev/ttyACM0 && echo success || echo failure

Si le résultat est failure, corrigez durablement les droits selon votre distribution, par exemple en ajoutant l’utilisateur au groupe qui possède le périphérique. Sur Home Assistant OS avec le module complémentaire officiel, commencez plutôt par la configuration du matériel et du chemin série.

Ordre de dépannage recommandé

1. Sauvegarder Zigbee2MQTT et noter la configuration actuelle.
2. Lire l’erreur détaillée dans le journal.
3. Vérifier le chemin stable du port série.
4. Vérifier la valeur adapter.
5. Éliminer le conflit ZHA ou une seconde instance.
6. Contrôler permissions, transmission USB et alimentation.
7. Mettre à jour Zigbee2MQTT si la version est ancienne, après sauvegarde.
8. N’envisager le reflash du coordinateur qu’en dernier recours.

FAQ

Faut-il réappairer tous les appareils ?

Non dans la majorité des dépannages de port ou de configuration. Ne supprimez pas la base Zigbee et ne changez pas de coordinateur sans avoir étudié la procédure de migration et sa compatibilité de sauvegarde.

ZHA et Zigbee2MQTT peuvent-ils partager le même dongle ?

Non. Chaque solution doit disposer de son propre coordinateur, ou l’une des deux doit être désactivée.

Pourquoi utiliser /dev/serial/by-id ?

Ce chemin identifie durablement le périphérique, contrairement à /dev/ttyUSB0 ou /dev/ttyACM0, qui peuvent changer après un redémarrage.

Sources officielles

• Zigbee2MQTT : échecs de démarrage et plantages
• Zigbee2MQTT : configuration de l’adaptateur
• Zigbee2MQTT : journalisation et mode debug

Sources

1. Zigbee2MQTT — Échecs de démarrage
2. Zigbee2MQTT — Configuration de l’adaptateur
3. Zigbee2MQTT — Journalisation