ZigBeeForDomoticZ plugin Wiki

Frequently Asked Questions

Troubleshooting

Errors

The errors specific to ZiGate coordinators (Decode8000, Communication error when transmiting a previous command, No DNS record configured for Zigate model, no decoder registered for MsgType) are in the FAQ for ZiGate.

Q1. Where can I get support ?

The first source of support is this Wiki.

You can also get support and ask questions :

To get a useful answer quickly, give from the start:

Q2. Where are the logs ?

By default, the plugin writes its logs in its own file: domoticz/plugins/Domoticz-Zigbee/Logs/PluginZigbee_XX.log, where XX is the hardware idx of the plugin in DomoticZ (for example PluginZigbee_05.log). A new file is started every night, and the last 7 are kept.

Errors, warnings and status messages also go to the DomoticZ log; debug messages only go to the plugin log file. See Debug mode for the details and the related settings.

Q3. Can I debug myself ?

Yes: see Debug mode to enable the debug messages of the part of the plugin you are interested in, for one device or for all. For pairing and connection difficulties, see also Troubleshooting pairing or connection.

Q4. Where can I find the list of supported Coordinators and Devices ?

Q5. Where can I find the coordinator firmwares ?

Q6. Can I use several coordinators in the same DomoticZ ?

Yes: add one instance of the plugin (one DomoticZ hardware) per coordinator. Each instance has its own Zigbee network, its own WebUI port and its own files. One instance manages all the devices paired to its coordinator: don’t create one DomoticZ hardware per device.

There is one known problem: with DomoticZ 2026.x and Python 3.11 (for example Debian 12 / Raspberry Pi OS Bookworm), the second instance fails to start with Cannot run the event loop while another loop is running. Use Python 3.12 or newer: see E16.

Q7. Can I fix the USB Port number ?

Some times, when you reboot your system, the USB Port (like dev/ttyUSB0) can change its number which cases a communication error with the coordinator. This is more an OS issue, but there are few hints :

Q8. My device is not updated in DomoticZ when interacting via a remote control or manually

For example : If you power off an Ikea bulb (with the physical switch) and then switch it on again, the status of the bulb is not updated in DomoticZ. And having the same issue with a remote controller which also doesn’t update it’s current state to DomoticZ.

If you encounter problems like the above example, it is most likely the automatic reporting is not configured correctly from the device end. Please follow below steps to fix this issue:

  1. Go to the Settings page of the WebUI.
  2. Activate the advanced settings.
  3. Check that the parameter allowReBindingClusters is enabled (it is by default).
  4. Switch off the bulb with the physical switch, wait for 10 seconds, then turn it on again. The rebinding process starts by itself, and the status problems should be fixed.

Some brands (Philips, Gledopto) don’t report their status at all: the plugin polls them, see Philips Gledopto. Ikea remote controls must have the coordinator in their group, see Ikea Tradfri.

The plugin adds its entry to the DomoticZ Custom menu itself when it starts (setting Enable Plugin WebUI from Domoticz Custom menu, enabled by default). If you don’t see it:

See Plugin integration for the details, including the cases where the automatic entry doesn’t work (DomoticZ over https, reverse proxy).

Q10. How do I change the Zigbee channel ?

Changing the channel in the WebUI Settings page and restarting the plugin doesn’t move an existing network to another channel. Use one of the methods of Change the Zigbee channel: the live channel change from WebUI > Admin > Coordinator keeps the paired devices (older battery devices may need a reset to follow).

Before changing the Zigbee channel, check which Wi-Fi channels are used around you: changing the Wi-Fi channel of your box is often simpler. See Zigbee and Wi-Fi and Real-time interference scan.

Q11. Can I use the DomoticZ Replace button to keep the history of a dead device ?

No. The DomoticZ Replace function doesn’t work with the widgets of the plugin: after a replace, some widgets of the new device stop being updated.

To replace a dead device by a new one and keep the history of its widgets, pair the new device, then use the Tools/replace_device.py tool of the plugin: see Replacing a Zigbee device while keeping its Domoticz history.

Q12. My ZiGate is no longer supported: what should I replace it with ?

The plugin no longer supports ZiGate coordinators. Pick a Texas Instruments, Silicon Labs, ConBee/RaspBee or Bouffalo Lab coordinator in Compatible coordinators, then follow Replace or migrate the coordinator: coming from a ZiGate, the devices have to be paired again.

Q13. How do I uninstall the plugin ?

  1. In DomoticZ, Setup > Hardware, delete the hardware of the plugin. This also deletes all its widgets, with their history.
  2. Delete the plugin folder domoticz/plugins/Domoticz-Zigbee.
  3. If you installed the Python modules in a virtual environment used only for the plugin, you can delete it too.

T1. My coordinator is not working

I can see in the log file some messages like that

Error: Zigbee: [ 70] Hard time getting Coordinator Version — likely a communication issue

or, after the plugin had started:

Error: Zigbee: Connection to coordinator lost, OSError (device disconnected or in use by another process), plugin restart might be required

This indicates a communication problem between the plugin and the coordinator. If the coordinator still doesn’t answer after a while, the plugin restarts itself and tries again. Cross-check the following in the DomoticZ Hardware settings of the plugin (see Plugin settings):

If it still doesn’t work, test the coordinator without DomoticZ and the plugin, with the zigpy command line tool installed with the plugin. Stop the plugin, activate the Python virtual environment of DomoticZ, then run an energy scan, for example for a Texas Instruments coordinator on /dev/ttyUSB0:

zigpy radio znp /dev/ttyUSB0 energy-scan

Use ezsp for Silicon Labs and deconz for ConBee/RaspBee. If this doesn’t work either, the problem is between the system and the dongle (port, rights, firmware). See also Real-time interference scan.

T2. My object can not be paired

T3. My object doesn’t work as expected

Please refer to Dealing with not-optimized devices and, to write a configuration file for it, device customization.

T4. The update from the WebUI says it succeeded, but the plugin version didn’t change

The WebUI shows Plugin Upgrade process completed without errors., but after the restart the plugin still shows the old version. Look at the output of the update for one of these cases:

See Plugin update for the manual update.

T5. My battery devices lose the connection, and raising the transmit power doesn’t help

Raising the transmit power of the coordinator lets it talk louder, but doesn’t make it hear the devices better: a battery device that is too far away still can’t reach it. Zigbee is a mesh network, and the solution is usually in the mesh:

See Build a good ZigBee mesh network, Real-time interference scan and Transmit power.

T6. The WebUI shows Unknown error right after a plugin restart

The WebUI is served by the plugin: while the plugin restarts, the WebUI can’t get any answer, and shows errors. Wait a minute or two after a restart before using the WebUI again.

If the error stays, check that the plugin is running in the logs. To investigate, enable the WebServer debug in WebUI > Tools > Debug (see Debug mode), reproduce the problem and look at the plugin log.

T7. The topology shows only the coordinator, or the routers disappear after a restart

This answer applies to plugin 9.1.008 and above, with a zigpy coordinator (Texas Instruments, Silicon Labs, ConBee/RaspBee, Bouffalo Lab).

Before 9.1.008, the zigpy topology scan had a bug: each scan kept the readings of the first one, so the reports could show all the devices linked to the coordinator only, or links to devices that had left the network. If you are on an older version, update the plugin first.

From 9.1.008:

  1. Check in the WebUI Settings page (advanced settings) that ZigpyTopologyReport and TopologyV2 (Network Topology based on routing and neighbourghs tables) are enabled. They are by default.
  2. In WebUI > Network > Topology, delete the reports made by the older versions: they were built the old way and give wrong results.
  3. Start a new scan and wait for it to complete: on a large network it takes several minutes, and the report only appears in the list once it is complete.

A battery device doesn’t route: it appears only through the router it is attached to, its parent. To see where the battery devices are attached, use the Associated devices button of the topology panel, and the Mesh graph.

T8. With a Texas Instruments coordinator, new devices leave and join again in a loop

You pair a device: it joins, leaves a few seconds later, joins again, and so on. Pairing never completes, even close to the coordinator. The devices already paired keep working. This happens on networks where many devices have been paired and removed over time.

The cause: the coordinator’s link key table is full. A Texas Instruments coordinator (Z-Stack) keeps one Trust Center Link Key (TCLK) entry for each Zigbee 3.0 device it has let into the network. The table has a fixed size, set when the firmware is built. With the Koenkk Z-Stack firmware it holds 200 entries (400 on a CC2674P10). Removing a device from the plugin doesn’t free its entry, and neither does a device leaving the network. When the table is full, the coordinator can’t give a new device its key: the device gives up, leaves, and tries again.

The fix: rewrite the table without the devices that no longer exist. Restoring a coordinator backup rewrites the whole table from the backup’s device list, so remove the old devices from the backup and restore it:

  1. Stop the plugin, then make a backup of the coordinator with zigpy-cli, as described in Manual backup and restore with zigpy-cli. Keep an untouched copy of the file. Replace /dev/ttyUSB0 with the port of your coordinator.

    zigpy radio znp /dev/ttyUSB0 backup coordinator-backup.json
cp coordinator-backup.json coordinator-backup.orig.json
  2. Open the JSON file. Each entry of the devices list has an ieee_address (16 hex characters, as the plugin shows it). The entries that have a link_key are the table entries: if there are close to 200, the table is full.
  3. Delete the entries whose ieee_address is not one of your current devices (see the device list in the WebUI). Keep the JSON valid (watch the commas).

  4. With the plugin still stopped, restore the edited file onto the same coordinator, then start the plugin and pair the device again. The restore is in the same zigpy-cli section, and in the zigpy-cli documentation:

    zigpy radio znp /dev/ttyUSB0 restore coordinator-backup.json

    The zigpy-znp tools do the same: python -m zigpy_znp.tools.network_backup and network_restore, see zigpy-znp backup and restore. If the restore goes wrong, restore the untouched copy.

Be careful in step 3: a device that still exists and that you removed from the file loses its link key, and must be paired again.

The table fills up again over time if you pair and remove many devices. Repeat the cleanup when it happens.

E1. Log error : No transport, write directive to XXX.XXX.XXX.XXX:8080' ignored

Time to time I see the following error message. Is that a big issue ? How can I get rid of it ?

Error: ZigBee: No transport, write directive to 'XXX.XXX.XXX.XXX:8080' ignored.

This error comes from DomoticZ. It appears when a WebUI page was left open and its connection timed out: when the page tries to refresh, DomoticZ has no connection to send the answer to. You can ignore it.

E4. Log Error : Error: (FindModule) Domoticz/DomoticzEx modules not found in interpreter

Error: (FindModule) Domoticz/DomoticzEx modules not found in interpreter.

This error appears when stopping the plugin. Ignore it.

E5. Missing module error

A ModuleNotFoundError or No module named ... error at startup (for example No module named 'zigpy' or No module named 'z4d_certified_devices') means that the Python modules of the plugin are not installed in the Python environment DomoticZ uses. Don’t install the modules one by one: requirements.txt installs all of them, with the versions the plugin needs.

Install them in the Python virtual environment of DomoticZ, from the plugin folder (see Plugin installation):

source /home/pi/Domoticz_Python_Environment/bin/activate
cd /home/pi/domoticz/plugins/Domoticz-Zigbee
python3 -m pip install -r requirements.txt --upgrade

If the modules are installed but still not found, see E17.

E6. Error : Error: <plugin's name> : You need to setup the URL Base to access the Domoticz JSON/API

This error appears when the DomoticZ parameter API base url is not correctly filled. More infos on step 2 Plugin settings.

E7. Error when updating python module: Building wheel for cryptography (PEP 517) ... error

When doing the command pip3 install -r requirements.txt or python3 -m pip install -r requirements.txt --upgrade you get this error.

ERROR: Failed building wheel for cryptography
Failed to build cryptography
ERROR: Could not build wheels for cryptography which use PEP 517 and cannot be installed directly

  1. upgrade or install the python module wheel, in the Python virtual environment of DomoticZ

     python3 -m pip install wheel --upgrade
  2. make sure your /tmp is large enough
  3. make sure you have enough swap, if requires , add some filesystem swap

E9. Error : ImportError: PyO3 modules may only be initialized once per interpreter process

Error: Zigbee: Call to function 'onStart' failed, exception details:
Error: Zigbee: Traceback (most recent call last):
...
Error: Zigbee:   File ".../cryptography/exceptions.py", line 9, in <module>
Error: Zigbee:     from cryptography.hazmat.bindings.rust import exceptions as rustexceptions
Error: Zigbee: ImportError: PyO3 modules may only be initialized once per interpreter process

This is related to a cryptography module more recent than the plugin supports. The plugin pins the versions it needs in constraints.txt (cryptography<=40.0.2), which requirements.txt applies. Reinstall the modules in the Python virtual environment of DomoticZ, from the plugin folder:

python3 -m pip install -r requirements.txt --upgrade

If the error persists, a more recent cryptography is probably installed system wide and found first: use a Python virtual environment, see Using Python Virtual Environment.

E11. Error : externally-managed-environment (Debian 12 or newer)

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

Debian 12 (Bookworm) and newer, and the matching Raspberry Pi OS releases, refuse pip install on the system Python. Don’t use --break-system-packages: install the modules in a Python virtual environment for DomoticZ, as described in Using Python Virtual Environment and Plugin installation.

E12. Error : Error: <plugin's name> : ModuleNotFoundError: No module named 'cchardet'

This error appears when you have several plugin instances and the charset-normalizer module is not the version the plugin expects. The plugin pins it in constraints.txt (currently charset-normalizer==2.0.11).

Check your version, in the Python virtual environment of DomoticZ:

python3 -m pip show charset-normalizer

If it is not the pinned version, reinstall the modules of the plugin, from the plugin folder (requirements.txt applies constraints.txt):

python3 -m pip install -r requirements.txt --upgrade

E13. Error : AttributeError: module 'lib' has no attribute 'OpenSSL_add_all_algorithms'

Error: Zigbee: (Zigbee) failed to load 'plugin.py', Python Path used was '...:/usr/lib/python3/dist-packages:...'.
Error: Zigbee: Traceback (most recent call last):
...
Error: Zigbee: File "/usr/lib/python3/dist-packages/OpenSSL/crypto.py", line 3279, in <module>
Error: Zigbee: lib.OpenSSLadd_all_algorithms()
Error: Zigbee: AttributeError: module 'lib' has no attribute 'OpenSSL_add_all_algorithms'

The root cause is a conflict between the pyOpenSSL of the system (/usr/lib/python3/dist-packages/OpenSSL) and the cryptography module installed for the plugin ref.

Use a Python virtual environment for DomoticZ, so that the plugin doesn’t load the system modules, and install the modules of the plugin in it (requirements.txt applies the cryptography<=40.0.2 pin of constraints.txt): see Using Python Virtual Environment.

E14. AttributeError: module ‘lib’ has no attribute ‘X509_V_FLAG_CB_ISSUER_CHECK’

Error: Zigbee: (Zigbee) failed to load 'plugin.py', Python Path used was '...:/usr/lib/python3/dist-packages:...'.
Error: Zigbee: Traceback (most recent call last):
...
Error: Zigbee: File "/usr/lib/python3/dist-packages/OpenSSL/crypto.py", line 1577, in X509StoreFlags
Error: Zigbee: CB_ISSUER_CHECK = lib.X509V_FLAG_CB_ISSUER_CHECK
Error: Zigbee: AttributeError: module 'lib' has no attribute 'X509_V_FLAG_CB_ISSUER_CHECK'

It is the same kind of conflict as E13, between the pyOpenSSL of the system and the modules installed for the plugin. The best fix is a Python virtual environment for DomoticZ (see Using Python Virtual Environment). Removing the system package also works, if no other software needs it:

sudo apt remove -y python3-openssl

E16. Error : Cannot run the event loop while another loop is running with several plugin instances

encountered a runtime error: Cannot run the event loop while another loop is running

With DomoticZ 2026.x and Python 3.11 (for example Debian 12 / Raspberry Pi OS Bookworm), the second instance of the plugin fails to start with this error. It is a Python 3.11 problem, reported to DomoticZ in domoticz/domoticz#6763. Restarting the failed instance (or waiting for it to restart by itself) usually gets both instances running.

DomoticZ itself writes a note about it at start-up on Python 3.11:

Status: Zigbee: Note: Python 3.11 detected. Plugins using asyncio inside sub-interpreters (shared="true" not set) can leak event-loop state between plugins on Python < 3.12 due to a global cache in CPython's _asyncio extension. If multiple asyncio-based plugins are active, prefer Python 3.12+ or set shared="true" in the plugin's XML manifest.

The fix is to run DomoticZ with Python 3.12 or newer (for example Debian 13 Trixie, which comes with Python 3.13), with the Python modules of the plugin installed for that version.

E17. ModuleNotFoundError although the modules are installed

The modules were installed for another Python than the one DomoticZ uses: another Python version, or the system Python instead of the virtual environment. The plugin may also report that a module has the wrong version (for example zigpy 0.83.0 found where 2.1.0 is required): an older copy of the modules is found first.

  1. Look for the Python version used by DomoticZ in the DomoticZ log: PluginSystem: Started, Python version '3.13.5'.
  2. Check that your virtual environment was created with the same version (<venv>/bin/python3 --version). If not, create it again with python3.xx -m venv and reinstall the modules.
  3. Check that DomoticZ is started with this virtual environment (VIRTUAL_ENV and PATH in the service). At start-up, the plugin writes VIRTUAL_ENV is set to: ... and PYTHONPATH is set to: ... in the DomoticZ log.
  4. Don’t mix the two methods: if the start script also sets a PYTHONPATH from an older installation, the modules of that folder are found first. Remove the PYTHONPATH line, see Older setups with PYTHONPATH.

If your virtual environment is in a mess, the simplest is to delete it and create it again, see Using Python Virtual Environment.

E18. Error : Z4D requires Python 3.11 or Domoticz version ... not supported

The plugin (stable9) requires Python 3.11 or newer and DomoticZ 2025.1 or newer, with the Extended Framework. DomoticZ 2026.3 is the recommended version.

See Plugin installation.

E19. Error during an update : detected dubious ownership in repository or You have uncommitted changes

fatal: detected dubious ownership in repository at '/home/pi/domoticz/plugins/Domoticz-Zigbee'

Error: You have uncommitted changes. Please commit or stash them first.

The plugin folder belongs to another user than the one running the update. It happens when the update runs as root (DomoticZ started as root, or a sudo command) on a folder owned by your user, or the other way round. git then refuses the folder, or sees every file as modified although you didn’t change anything.

Give the plugin folder to the user DomoticZ runs as, then run the update again. For example, if DomoticZ runs as pi:

cd /home/pi/domoticz/plugins/Domoticz-Zigbee
sudo chown -R pi:pi .
git status

git status must then show no modified file. If it still shows files you really changed, put them aside with git stash -u (see Upgrading from stable8 to stable9), or reset them as described in Plugin update.

E20. Error : Domoticz widget creation failed ... Check that Domoticz can Accept New Hardware

Error: Zigbee: Domoticz widget creation failed for <NwkId>/<Ep> <widget type> (unit <unit>). Check that Domoticz can Accept New Hardware, and see the Domoticz log for the reason it refused.

DomoticZ refused to create a widget for a device. The plugin keeps the device and tries again a few times; if it still fails, it stops trying until the next restart.

  1. In DomoticZ, Setup > Settings > System, check that Accept new Hardware Devices is enabled (see Add a new device).
  2. Look in the DomoticZ log, at the same time, for the reason DomoticZ gave.
  3. Then restart the plugin, or use Recreate widget in WebUI > Admin > Provisionning to create the widgets of the device again.