Thread and Matter Network Troubleshooting: Common Pitfalls

Overview

Most Matter over Thread failures are not device faults. They are network faults. Thread and Matter lean on parts of the network that traditional smart home protocols never touched: IPv6, link-local multicast, and mDNS service discovery across every hop between your phone, your Thread border router, and Home Assistant.

This guide collects the pitfalls that cause the classic symptoms: commissioning that hangs on “Setting up…”, devices that pair and then disappear, and devices that work in Apple Home or Google Home but never in Home Assistant.

For step-by-step commissioning failures and multi-fabric conflicts, see Matter Device Pairing Failures and Connectivity . This page focuses on the network layer underneath that flow.

Pitfall 1: The Companion App Is Connected via the Remote (External) URL

This one is easy to miss because everything looks fine. The device connects over Bluetooth, the Companion App shows the device, and then setup sits on “Setting up…” with “This may take a few minutes” and never finishes.

The cause is the Companion App itself. Even on your home Wi-Fi, the app can get stuck routing through your remote (External) URL, for example a Nabu Casa Cloud or Selora Homes remote access URL, instead of the local Internal URL. Matter over Thread commissioning has to hand Thread credentials and local network data between the phone and Home Assistant over the LAN. When the app is talking to Home Assistant through the cloud, that local handoff never completes and the flow hangs indefinitely.

This has been observed on some versions of the Android Companion App, where the Matter commissioning service may choose the External URL instead of the Internal URL during local commissioning. It selects that connection separately from the rest of the app, so it can land on the external address for an operation that is inherently local. When that happens, the app tries to reach the external URL, times out, and the commissioning command never runs.

How to confirm and fix

1. In the Companion App, go to Settings > Companion App.
2. Open the connected home (named Home by default, or your server name).
3. Look at Status > Connect via. During local commissioning this should read Internal URL, not External URL.
4. If it shows External URL, select Update server information.
5. Confirm Connect via now reads Internal URL.
6. Return to the Matter setup flow and pair the device again.

Pitfall 2: IPv6 Is Disabled, Filtered, or Broken

Thread is an IPv6-only mesh, and Matter relies on IPv6 to reach Thread devices through the border router. If IPv6 is off or partially broken on your LAN, Thread commissioning fails or devices drop off after pairing, even though Wi-Fi Matter devices may still work.

What to check

• IPv6 enabled on the Home Assistant host. Go to Settings > System > Network and confirm IPv6 is set to Automatic or Static, not disabled. This is the setting people most often miss: the router looks modern and the phone has IPv6, but the HA host itself has IPv6 turned off, and commissioning dies at the Bluetooth-to-network handoff.
• You do not need internet IPv6. An ISP that hands out an IPv6 prefix is not required. Link-local and ULA addressing is enough for the local Matter fabric, so do not go chasing a public IPv6 address to make this work.
• IPv6 enabled on the LAN. Many consumer routers ship with IPv6 disabled or in a mode that does not address the LAN. Enable it so the host, the border router, and your phone can reach each other over IPv6.
• Router advertisements (RA) and multicast are not filtered. Thread and the border router depend on IPv6 Neighbor Discovery and multicast. Firewall rules or “IPv6 privacy” features that block RA or multicast will break the path between the Thread mesh and the rest of the LAN.
• Docker / Supervised installs need host networking and IPv6. The Matter Server and OpenThread Border Router add-ons must see the host’s IPv6 stack and multicast directly. A container on a bridge network without IPv6 will not route Thread traffic. Home Assistant OS handles this for you; custom Docker setups often do not, and running the Matter Server standalone in Docker is not an officially supported configuration.

Pitfall 3: mDNS / Multicast Blocked Across VLANs or Wi-Fi

Matter discovers services with mDNS (multicast DNS, UDP port 5353). Thread border routers advertise themselves with the _meshcop._udp service, and Matter nodes use _matter._tcp and _matterc._udp. If multicast does not flow between your phone, Home Assistant, and the border router, discovery fails and commissioning times out even when everything is powered and online.

Common blockers

• VLAN segmentation without an mDNS reflector. Putting IoT devices on a separate VLAN from Home Assistant is good practice, but Matter/Thread needs mDNS to cross that boundary. Enable an mDNS repeater/reflector (Avahi, UniFi’s “mDNS” toggle, pfSense/OPNsense Avahi package) between the VLANs, and allow UDP 5353 both directions.
• Wi-Fi client isolation / AP isolation. Guest networks and some default Wi-Fi configs block client-to-client traffic, so your phone can never see Home Assistant or the border router. Disable client isolation on the network used for commissioning.
• IGMP snooping without a querier. On managed switches, IGMP snooping can silently drop multicast if there is no active querier, starving mDNS. Either disable snooping on the relevant VLAN or configure a querier.
• Wi-Fi multicast rate limiting. Some access points throttle or drop multicast to save airtime, which makes discovery flaky and intermittent rather than fully broken.

Pitfall 4: Thread Network Fragmentation (Multiple Border Routers)

Thread border routers from different ecosystems (Apple HomePod/Apple TV, Google Nest, and your Home Assistant OpenThread Border Router) can each form their own isolated Thread network. When that happens, a device commissioned onto one network is invisible to controllers on another, and devices drift offline when the “wrong” border router is the only one nearby.

What to check

• Go to Settings > Devices & Services > Thread and look at the listed networks and border routers.
• All border routers you want to cooperate should show the same network (shared Thread dataset / credentials). If you see multiple network names, they are fragmented.
• Decide on a preferred network. Ideally the Apple and Google ecosystems adopt Home Assistant’s Thread dataset (or vice versa) so there is one mesh. Sharing credentials both ways lets a new border router join the existing network instead of forking a rival one.
• Keep at least one border router always powered. Thread devices lose their path to Home Assistant when their only nearby border router is unplugged or asleep (an Apple TV in deep sleep, a HomePod that was moved).

An Apple-only border router setup has a further quirk: Home Assistant driven firmware updates can fail with “Target node did not process the update file” because Apple border routers do not forward the packets those updates need. Adding one non-Apple border router resolves it.

Pitfall 5: OTBR Radio and Channel Conflicts

• Zigbee and Thread share 802.15.4 on 2.4 GHz (channels 11 to 26). On the same or adjacent channel they interfere. Keep them well apart, for example Zigbee on channel 15 and Thread on channel 25. The cleanest Thread channels are usually 25 and 26.
• Prefer separate radios over multi-PAN. Running Zigbee and Thread on one combo dongle (multi-PAN) is fragile: enabling OpenThread Border Router on a dongle that was serving Zigbee has been reported to break the working Zigbee setup. Multi-PAN also forces both protocols onto the same channel, trading the cross-protocol gap for shared-channel contention. A dedicated radio for each is the reliable choice.
• Thread channel vs Wi-Fi channel overlap. Heavy 2.4 GHz Wi-Fi (channels 1, 6, 11) overlaps the 802.15.4 band. Move Wi-Fi to a cleaner channel or shift the Thread channel. In OTBR logs, ChannelAccessFailure means the channel is too congested to transmit.
• Firmware. Keep the border router firmware, the Matter Server add-on, and Home Assistant Core current. Thread and Matter are moving fast and many connectivity bugs are fixed in updates.

Pitfall 6: Phone-Side Permissions and 2.4 GHz During Commissioning

Commissioning uses the phone’s Bluetooth and local Wi-Fi, so the phone’s own settings can block it:

• Android location permission must be “Allow all the time.” Android gates Wi-Fi network access behind location, and “While using the app” is not enough for background commissioning. Grant the Companion App full location access.
• Google Play Services / Matter module. On Android the Matter support is delivered through Play Services and can take time to download on a fresh phone. Keep Play Services updated. The “Commission using Companion app” button only appears in the app, never in a browser.
• Put phone, Home Assistant, and the device on the same 2.4 GHz SSID. Most Matter Wi-Fi devices onboard on 2.4 GHz only. Band steering that moves the phone to 5 GHz, or a separate SSID, can stall the flow. Keep everything on one plain 2.4 GHz network while pairing.
• Stay close. Keep the phone within a meter or two of both the device and the border router. The initial Bluetooth step and Thread join are range-sensitive.

Quick Diagnostic Checklist

When to Escalate

If commissioning still fails after the above:

1. Confirm the Companion App is on the Internal URL and fully updated.
2. Verify Home Assistant, the Matter Server add-on, and OTBR firmware are current.
3. Factory reset the device and recommission through the Companion App on the same subnet as Home Assistant.
4. Capture the Matter Server add-on logs during the attempt, since they show the exact stage where the handshake stalls.

Further Reading