Adding a Matter-over-Thread device

The pairing steps, and the four failures that each look like a broken border router but are not — including the Android one that is fixed on the phone.

Updated 26 August 2026 matterthreadtroubleshooting

Four steps. The phone stays on the house Wi-Fi. Android needs a credentials sync once. Then you scan the code.

If you already have ESPHome Bluetooth proxies, skip the phone: commission Matter with a Bluetooth proxy. If the Thread panel is empty, start at Thread and Matter with a hosted Home Assistant. The picture of the radios is how Thread and Matter actually work.

Pairing

1. Put the phone on the same home Wi-Fi as the border router. Not guest Wi-Fi, not mobile data.
2. Android only, once per phone: companion app → Settings → Companion app → Troubleshooting → Sync Thread credentials. Expect a confirmation that Home Assistant's Thread credentials were added to the phone.
3. Put the device into pairing mode near the border router, or near an ESPHome Bluetooth proxy.
4. Add it from the companion app and scan the code.

Expect a firmware update to start on its own shortly after pairing. Ours went to Matter 1.2.0 unprompted.

A device that pairs successfully becomes a Thread router itself, so the next one can mesh through it rather than needing line of sight to the dongle.

Alternative: skip the phone's Thread stack

Put the device next to an ESPHome Bluetooth proxy and add it from the Home Assistant web interface. That path is written up as commission Matter with a Bluetooth proxy. It needs ble_proxy on the Matter Server add-on and Home Assistant 2026.06 or later, and it never involves Google Play Services.

When it goes wrong

The same four words — "needs a border router" — cover four different faults.

"Your device requires a Thread border router"

Home Assistant has one, and this message is not about Home Assistant. On Android, Matter-over-Thread commissioning goes through Google's Thread stack, which checks whether the phone holds credentials for a border router it recognises. Home Assistant's does not count until the phone has the same dataset — and the companion app stopped syncing that automatically.

So: Sync Thread credentials (step 2 above), then pair again. If it still refuses, the phone is probably holding an empty Google Thread network; clear Google Play Services storage and cache, sync again, retry.

Google Home Mini and Nest speakers are not Thread border routers, so they cannot satisfy that check either.

Hangs on "checking connectivity to Thread network"

The device has already joined. This is a routing failure, not a radio one, and the evidence is on the border router: a new neighbour appears in the router table while the phone sits on that screen, and the dataplane counters stay at zero.

The cause is almost always IPv6 forwarding being off on the border-router host. See the sysctls in build a Thread border router — with network_mode: host, a container cannot set them for you.

Once forwarding is on, ot-ctl br counters shows hundreds of packets in both directions within seconds of a successful pairing. That is the proof.

A device that timed out on this screen may need a factory reset before it will advertise for pairing again.

Fails instantly on the QR scan

It never reached Bluetooth, so nothing about Thread is involved. A hosted Home Assistant has no Bluetooth hardware of its own, so the Bluetooth hop has to come from somewhere: the companion app's phone radio, which is what the web interface will steer you to, or the Matter Server add-on's ble_proxy option using your ESPHome proxies.

Thread panel says there is no border router

Usually the border router needs to re-announce itself, especially just after a Home Assistant restart or update. Restart the border-router container.

If it is genuinely absent and restarting does not bring it back, the problem is usually that IPv6 multicast is not reaching Home Assistant — see HomeLink L2, and tell support. Include that IPv4 discovery works, if it does.