How to Fix the ‘Error While Starting Zigbee-Herdsman’

Zigbee2MQTT is a widely-used tool for integrating Zigbee devices with home automation systems like Home Assistant. However, encountering the “Error while starting zigbee-herdsman” is a common problem among users. These issues can arise from incorrect configurations, hardware conflicts, or firmware compatibility problems. In this guide, we’ll address these challenges and provide practical solutions with real-world examples.

Common Causes and Fixes

1. Port Lock Issues: Fixing Error While Starting Zigbee-Herdsman

Issue: The error log shows:

Error: Resource temporarily unavailable. Cannot lock port.

Cause: Another application (e.g., Zigbee Home Automation – ZHA) is accessing the same port as Zigbee2MQTT.

Solution:

• Use the following command to check which process is locking the port:

ls -l /proc/[0-9]/fd/ | grep /dev/ttyACM0

Replace /dev/ttyACM0 with your adapter’s port.

• Stop the conflicting application or uninstall ZHA. For example:

serial:
  port: /dev/serial/by-id/usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2
  adapter: ezsp

Log Example:

Zigbee2MQTT:error: Error Resource temporarily unavailable Cannot lock port

2. Incorrect Serial Port Configuration: Troubleshooting Zigbee-Herdsman Errors

Issue: Zigbee2MQTT fails to connect to the Zigbee adapter.
Cause: An incorrect or undefined port in the configuration file.
Solution:

• Identify the correct port:

ls -l /dev/serial/by-id/

• Update configuration.yaml with the correct serial port:

serial:
  port: /dev/serial/by-id/usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2
  adapter: ezsp

Log Example:

Zigbee2MQTT:error 2024-03-15 10:59:38: Error: spawn udevadm ENOENT

3. Database File Corruption: Resolving Zigbee-Herdsman Errors

Issue: Logs show missing or empty files like state.json or database.db.
Cause: Corruption in the Zigbee2MQTT database.
Solution:

• Restore the database from a backup or remove the corrupted file:

rm /path/to/database.db

• Restart Zigbee2MQTT to regenerate the file.

Log Example:

debug: Can't load state from file /app/data/state.json (doesn't exist)

4. Firmware Incompatibility: Fixing Zigbee-Herdsman Startup Errors

Issue: Errors indicate unsupported protocol or connection failure.
Cause: The firmware on the Zigbee dongle is outdated or incompatible with Zigbee2MQTT.
Solution:

• Update your firmware using Silabs Firmware Builder.
• Recommended firmware:
  • ncp-uart-hw_6.10.3_115200.gbl
  • For Sonoff Dongle: Ensure the firmware matches your Zigbee2MQTT version.

Log Example:

Error: Adapter EZSP protocol version (9) is not supported by Host [13-14].

5. Node.js Version Compatibility: Addressing Zigbee-Herdsman Errors

Issue: Zigbee2MQTT fails to initialize.
Cause: Node.js version mismatch.
Solution:

• Verify your Node.js version:

node -v

• Use the version recommended by Zigbee2MQTT.

6. Hardware Connection Issues: Fixing Zigbee-Herdsman Errors

Issue: Frequent disconnections or failure to start.
Cause: Poor USB connection or signal interference.
Solution:

• Use a USB 2.0 port or an extension cable to minimize interference.
• Example configuration:

serial:
  port: /dev/ttyUSB0
  adapter: ezsp

Log Example:

Zigbee2MQTT:error: Error while opening serialport: No such file or directory.

Real-World Troubleshooting Tips

1. ZHA Conflict:

If ZHA is installed, Zigbee2MQTT won’t start. Uninstall ZHA or ensure the two don’t share the same port.

2. Downgrade Firmware:

Users resolved issues by downgrading the firmware:

image: koenkk/zigbee2mqtt:1.36.1

3. Use Debug Logs:

Enable debug logging for detailed insights:

advanced:
  log_level: debug

4. Hardware Adjustments:

Remove USB extension cables if they cause signal issues.

Change the baud rate for EZSP adapters:

baudrate: 115200

Example Configuration File

Here’s a working configuration for Zigbee2MQTT:

serial:
  port: /dev/serial/by-id/usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2
  adapter: ezsp
mqtt:
  server: mqtt://192.168.1.8:1883
  base_topic: zigbee2mqtt
homeassistant: true
advanced:
  log_level: debug

Conclusion

Troubleshooting “Error while starting zigbee-herdsman” can be complex, but identifying the root cause is key. Focus on:

• Ensuring correct port configurations.
• Keeping firmware and software versions compatible.
• Removing conflicting services like ZHA.

For more detailed steps, visit the official Zigbee2MQTT documentation. If you’re still facing issues, feel free to comment down below for assistance.