Hi everyone,
I’ve spent the last several days troubleshooting this and I’m at the point where I’m wondering if this is a bug or if I’ve overlooked something.
System
Home Assistant Green
Dedicated Home Assistant OS installation (not Docker or a VM)
Home Assistant Core 2026.8.0
Supervisor 2026.07.5
Home Assistant OS 18.2
Frontend 20260729.5
Matter Server 9.1.1
OpenThread Border Router 3.1.0
Home Assistant Connect ZBT-2 configured as the OTBR
Netgear RS280S router
Problem
I cannot commission any Matter-over-Thread devices into Home Assistant.
I’ve tested both:
Onvis Matter-over-Thread smart plugs
Eve Matter-over-Thread smart plugs
Both fail identically.
Android behavior
Using a Pixel 9 Pro with the Home Assistant Companion app:
Scan the Matter QR code.
The device is found.
Thread credentials are transferred.
“Checking connectivity to Thread network” appears.
After about a minute it fails with: Can’t reach device. Make sure your phone is connected to Wi-Fi.
The phone remains connected to Wi-Fi throughout the process.
iPhone behavior using an iPhone SE (3rd generation):
The device is discovered and begins setup, but never progresses beyond: Setting up…
It simply spins indefinitely.
Troubleshooting already performed
Factory reset the Pixel 9 Pro.
Cleared Google Play Services cache/data.
Deleted and recreated the Matter integration.
Deleted and recreated the Thread integration.
Deleted and recreated the OpenThread Border Router.
Created a completely new thread dataset/network.
Factory reset my Google Nest Hub 2nd gen.
Factory reset my Google TV Streamer.
Confirmed Android received the new thread credentials after recreating the thread network.
Verified IPv6 is enabled.
Rebooted Home Assistant multiple times.
Tested with both Onvis and Eve Matter-over-Thread devices.
Unplugged all other thread border routers (Google TV Streamer and Nest Hub) so the Home Assistant ZBT-2 was the only active thread border router during commissioning attempts. The behavior did not change.
Used the official Thread Tools app, which successfully discovered the Home Assistant thread network, identified the Home Assistant OTBR as the thread leader, and reported the network as healthy.
Additional observations
OTBR starts normally and becomes the Thread Leader.
Matter Server starts normally without any obvious errors.
The Thread Tools app can communicate with the Home Assistant Thread network successfully.
Android correctly switched from my previous Thread network to the newly created one, so Thread credentials appear to be transferring successfully.
Despite recreating the entire Matter/Thread stack from scratch, commissioning behavior did not change.
At this point I’m not sure where the failure is occurring. Since both Android and iOS fail, and two different Matter-over-Thread vendors behave identically even after rebuilding the entire Matter/Thread stack, I’m wondering if there’s another debug log I should capture or whether this should be reported as a GitHub issue.
I’m happy to capture additional debug logs or run further diagnostics if someone can point me toward the most useful ones.
So, you are absolutly sure that IPV6 is activated in your WiFi Router and that HA an your phones are in the same network (no Virtual Networks or similar?)
Is your ZBT-2 Thread network set to preferred?
Did you manually enable IPv6 forwarding in the HA Terminal by
“ha docker options --enable-ipv6=true” ?
If not, do that and restart HA!
I dont know if the HA Green has a built-in Bluetooth radio, if yes you can try direct commissioning the Thread Credentials from your HA Green to the Matter Device by enabling “BLE proxy” in the configuration of the matter server app. Then you can commission the device (close to your HA Green) directly in the Matter Server App. This has the nice advantage, that you can keep Google or Apple out of the process. You have to type in the matter code manually. Don’t worry, this won’t break the option to add devices by scanning QR-Codes.
IPv6 is enabled on both my network and Home Assistant, and all devices are on the same LAN with no VLANs or guest networks.
The ZBT-2 Thread network is set as the preferred Thread network in Home Assistant and on devices I was attempting to commission on.
I haven’t manually enabled ha docker options --enable-ipv6=true because I’m running Home Assistant Green (Home Assistant OS), not Docker, so I don’t believe that pertains to me.
I also tried physically unplugging my other Thread Border Routers (Google TV Streamer, Nest Hub, Echo devices) so only the ZBT-2 was active, but commissioning still failed on both Android and iPhone.
My next step is to try adding a USB Bluetooth adapter to the HA Green so I can test BLE commissioning directly from Home Assistant and rule out the phone commissioning path.
The “HA docker xxx” command has nothing to do with the system HA is running on. HA itself is subdivided in dockers. So do yourself a favour and put that in the Terminal!
You have to activate that manually since Core Update 17.xx or so. Then restart HA and try again.
A BT Dongle wont help, if IPv6 forwarding is not enabled. Does the Green have no Bluetooth radio built in? If it has, there’s no need for extra hardware because the latest Matter Server App versions can use BLE proxies for commissioning. You just have to enable it in the Matter Server Configuration.
You were right. ha docker info showed enable_ipv6: null. I enabled it, rebooted the HA Green host, and confirmed it now shows enable_ipv6: true. Unfortunately commissioning still fails the same way. Android gets “Can’t reach device / Make sure your phone is connected to Wi-Fi,” and iOS eventually returns “Unable to add accessory / Pairing failed.”
My Green does not have built-in Bluetooth. I have a supported USB Bluetooth adapter coming, so once it arrives I’ll try BLE commissioning directly through Matter Server as you suggested.
The first setup of Matter over Thread can be a pain in the a… but once you get it running it has some advantages over zigbee imho.
The direct pairing approach is also my favourite avoiding Google to be to much involved !-)
You should also make sure to choose a channel that doesn’t collide with WiFi (2.4Ghz), Bluetooth and Zigbee. Channel 25 for Thread is a good start if your WiFi is set to channel 1,6 or 11. Reduce the 2.4 Ghz Wifi Bandwith to 20 Mhz, if your router lets you do that, otherwise it could interfere with the Thread signals.
Thanks! Enabling IPv6 forwarding and rebooting did the trick. Phone commissioning still wasn’t working, so I added a USB Bluetooth dongle and enabled BLE commissioning in Matter Server.
I was able to commission an Eve Energy and, after moving the HA Green closer to the lock, finally got my Aqara U400 commissioned directly into HA as well. Everything is working now. Appreciate the help!
There actually isn’t a setting called “BLE Proxy” inside the Matter Server add-on. That terminology gets mixed up with HA’s Bluetooth Proxy (ESP32) feature.
What you need to do is pass a physical Bluetooth adapter directly to the Matter Server add-on so it can broadcast the local Bluetooth handshake needed for Matter-over-Thread commissioning. I bought a $10 dongle and a USB extender because distance matters.
Here is how to set it up:
1. Verify Your Bluetooth Adapter Index
Go to Settings - Devices & Services - check your Bluetooth integration.
Look at the adapter name listed on the card (it will say something like hci0 or hci1).
Important: If HA pops up a card asking to “Add” the Bluetooth integration for that adapter, click Ignore. You want the Matter Server container to have direct access to it rather than HA Core hijacking it.
2. Configure Matter Server to Use the Bluetooth Adapter
Go to Settings - Add-ons - Matter Server.
Click the Configuration tab.
Toggle on Show unused optional configuration options (top right menu or switch).
Look for Bluetooth Adapter ID:
Set it to 0 if your adapter is hci0.
Set it to 1 if your adapter is hci1.
Click Save and Restart the Matter Server add-on.
3. Direct Commission via the Matter Web UI
Once restarted, you can commission directly without relying on a phone’s Bluetooth:
Go to Settings - Add-ons - Matter Server - Open Web UI.
Click Commission Node - Commission new Thread device.
Paste your Thread Active Dataset TLV and type the manual setup code.
(Note: Bluetooth is only used for the initial ~10-second credential exchange. Keep in mind that range matters during that handshake. If it times out, the BLE signal between the host adapter and the device might be dropping frames due to distance or USB interference).
Then I got an invalid data set error when pasted the data set.
Update:
While it would not accept the Dataset ID I obtained from the border router section in HA it did accept the Key I obtained from Nanoleaf app for my TBR (SmartThings Station Hub).
It then asked for a pairing code which I entered, it tried for quite a while then failed.
That’s the obsolete “old” approach. The latest versions of the Matter Server App can now use integrated BT-Radios for commissioning. When you have a Bluetooth Dongle or a built-in BT-Radio (like Raspberry Pis), or even some compatible Shellies, then you don’t have to do the workaround with a “non-integrated” BT-Dongle. You just go to Settings/Apps/Matter Server App/Configuration then “Enable BLE proxy” will do the trick.
Edit: When i first tried the BLE-Pairing, it kept failing, trying to add an IKEA Grillplats plug. Then i found out, that you have to do it in a particular way: keep the device you want to pair completely powerd off, first start the commisioning process by typing in the Matter Code and let the searching for devices process begin, THEN plug in or power on (e.g. put in batteries) the specific Matter device.
At least that’s the only way it worked for me. I think it had something to do with the BLE Advertisements in the “memory”.
My “Amateur explanation”: When you power on the device you want to pair, it gets instantly discovered by the BLE-Proxy and kept in memory for some time (minutes). When you now start the Matter commissioning process, this already discovered and memorized device somehow won’t get recognized as Matter device that waits for the Thread Credentials to be sent via BT. And the commissioning process fails.
When you wait some time until the BLE proxy has “forgotten” this device (you can check that in the Bluetooth topology map), and then retry it in the first mentioned order, it works.
Just my findings. HA experts might explain that in a more sophisticated way, or prove me wrong. !-)
I know you’ve fixed this through bt, but I found you by facing a similar problem. Do you have T-Mobile? If so, there seems to be a basically unfixable issue with ipv6. My fix was to set up an entirely separate wifi network, configure it with ipv6, and connect both HA and my cell phone to the alternate network (just connect your T-Mobile box to the other Wi-Fi via LAN). Matter connection started working easily.
I can’t explain how to set up the wifi–I’m not technical so I had Claude walk me through it and forget what I had to do. But just confirming there may be an actual (albeit cumbersome) fix to this.
