ZBT-2 / OpenThread Border Router: serial port locked and RCP failures caused by Z-Wave JS UI

Configuration Matter/Thread
1

Knowledge preservation note

This issue was diagnosed with the assistance of GPT. Users who solve technical problems with AI assistance are encouraged to document verified solutions in the relevant public forums, issue trackers, or knowledge bases. As AI systems increasingly rely on publicly available technical knowledge, solutions that remain confined to private AI conversations risk reducing the completeness and currency of the searchable human knowledge base over time.

Home Assistant Connect ZBT-2 / OTBR failing because another add-on locks the serial port

Environment

Home Assistant OS 18.2
Home Assistant Core 2026.8.3
Home Assistant Supervisor 2026.07.5
OpenThread Border Router 3.1.1
Home Assistant Connect ZBT-2
OpenThread RCP firmware 2.7.2.0
Raspberry Pi 4

Symptoms

OTBR repeatedly failed with either:

Serial port ... is already locked by another process

or, when it managed to start:

radio tx timeout
RCP failure detected
Too many rcp failures, exiting

The ZBT-2 itself was correctly detected as:

/dev/serial/by-id/usb-Nabu_Casa_ZBT-2_...

ZHA correctly used a separate SONOFF Zigbee dongle.

The system had previously worked. The problem appeared after USB devices had been disconnected/reconnected during unrelated testing.

Diagnosis

Z-Wave JS UI was installed and running although no Z-Wave controller was configured:

devices: []

The add-on nevertheless had UART/udev access enabled.

With Z-Wave JS UI running, OTBR repeatedly encountered a locked serial port or RCP communication failures.

After stopping Z-Wave JS UI and physically reconnecting the ZBT-2, OTBR remained running for more than 60 seconds.

The Home Assistant Connect ZBT-2 integration was then re-enabled and OTBR remained stable.

OTBR subsequently reported:

Role detached -> leader

and:

Backbone Router becomes Primary!

Matter Server also recovered. Previous ENETUNREACH errors stopped after the Thread border router became operational.

Resolution

  1. Stop Z-Wave JS UI.
  2. Disable its automatic startup if it is not being used.
  3. Unplug the ZBT-2 for approximately 10 seconds and reconnect it.
  4. Start OpenThread Border Router.
  5. Verify that OTBR remains started.
  6. Re-enable the Home Assistant Connect ZBT-2 integration if it was disabled during troubleshooting.
  7. Verify that OTBR reaches Thread leader state and Matter devices reconnect.

Additional finding

The Raspberry Pi also had repeated undervoltage events. Replacing the PSU eliminated those events and was necessary for overall system reliability, but OTBR continued to fail until the Z-Wave JS UI/serial-port conflict was removed. Therefore, in this case undervoltage was a separate problem rather than the primary cause of the Thread failure.