Short Answer: The Accessory Usually Got Past Bluetooth and Failed on the Local-Network Handoff

If Home Assistant stalls at "Checking network connectivity" while you add a Matter device, the accessory usually got far enough to exchange credentials over Bluetooth. The failure is often happening one step later, when the device is supposed to start talking over Wi-Fi or Thread and Home Assistant is supposed to discover it on the local network.

For Wi-Fi Matter, the common miss is the wrong SSID, the wrong band, or discovery traffic being filtered. For Matter over Thread, the common miss is the wrong Thread credentials on the phone, a border router that is not really joined the way you think it is, or a broken local IPv6 path between Home Assistant, the border router, and the device. Home Assistant's Matter docs say Matter depends on local IPv6 and mDNS traveling freely. Those same docs also say you do not need IPv6 internet or DHCPv6 from your ISP, but IPv6 support still has to be enabled on Home Assistant itself.

Tara's rule: do not factory-reset the accessory three more times until the phone, Home Assistant, and the intended Thread or Wi-Fi path agree about which local network they are using.

Why This Question Is Current and Worth Publishing Now

The demand signal is not vague. It is active right now. On the Home Assistant Community's Matter/Thread category pages visible in early June 2026, current onboarding topics included Pairing IKEA Grillplats plug issues - ipv6? with 2,288 views on June 6, 2026, Home Assistant Green + ZBT-2 do not connect to Thread devices on June 7, 2026, and Can't add Matter devices (stuck on Checking network connectivity) with 2,752 views on the next category page. The category pages also showed Can't add new Matter devices using HA with Apple TV as TBR, which reinforces that the issue is not limited to one radio brand or one phone platform.

Reddit is using the same language. Recent r/homeassistant threads describe Home Assistant stuck at checking connectivity to the Thread network and the companion app using the wrong Thread network during commissioning. GitHub issues from April 2026 track closely related edge cases: Thread credentials not reaching an iPhone, Home Assistant allowing Matter setup while IPv6 is disabled, and ZBT-2 plus OTBR setups showing NoAddress warnings with no successful commissioning. That does not prove Matter is broadly broken. It does show that current onboarding failures cluster around the same local-network layers. That interpretation is an inference from community patterns, not a direct Home Assistant claim.

Local smart home hub, router, and accessories showing the boring network layers behind Matter onboarding
When Matter onboarding fails, the culprit is often not the QR code or the brand. It is the boring local stack underneath: phone credentials, IPv6, multicast, Wi-Fi placement, or VM networking.

What the Spinner Actually Means

Home Assistant's Matter docs describe the onboarding flow in plain terms: your phone connects to the accessory over Bluetooth, sends the network credentials, and then the accessory begins communicating over its native interface, which is either Wi-Fi or Thread. The companion app is involved in the commissioning flow, but the device does not stay on Bluetooth after onboarding.

That makes the spinner easier to interpret.

Stage you see What likely succeeded What is usually failing next
Connecting to device The phone found the accessory over Bluetooth. The local-network path has not been tested yet.
Generating Matter credentials The phone and OS commissioning flow are still alive. The accessory still has to move onto Wi-Fi or Thread.
Checking network connectivity Credential handoff probably happened. The accessory cannot finish the IP or Thread handoff cleanly, or Home Assistant cannot discover it afterward.
Can't reach device or timeout The pairing flow reached the network stage. Discovery, IPv6, multicast, the wrong Thread network, or the wrong Wi-Fi path is still blocking the finish.

Start With the Radio Type, Not the Brand

1. Confirm whether it is Wi-Fi Matter or Matter over Thread

Home Assistant's Matter docs say to look for both the Matter logo and either the Wi-Fi or Thread logo on the packaging. That first split changes the whole troubleshooting path. Wi-Fi Matter does not need a Thread border router. Matter over Thread does.

If you are actually seeing the separate Home Assistant message that says "Your device requires a Thread border router", start with Tara's dedicated guide for that error at Why Home Assistant Says "Your Device Requires a Thread Border Router". This article is about the later network-connectivity stall, which can happen on Wi-Fi Matter or Thread Matter.

2. Put the phone on the right network and in the right physical place

Home Assistant's Matter docs say that if you are adding a Wi-Fi-based Matter device, your phone should be on the same 2.4 GHz network where you want that device to operate. Many Matter accessories still rely on 2.4 GHz Wi-Fi during onboarding. If the phone is on a guest SSID, a differently isolated SSID, or a fancy network that hides multicast, the pairing flow can reach the network step and still fail.

If you are adding a Thread-based Matter device, the Matter docs say the phone should be in close range of both the border router and the device. The Bluetooth stage can succeed while the Thread stage still fails if the phone is too far away, on the wrong local segment, or speaking to the wrong preferred network.

3. If it is Thread, sync or import the credentials before retrying

If Home Assistant created the Thread network, the official Thread docs say the phone needs those credentials before you add Matter-over-Thread devices. On Android, the docs point to Settings > Companion app > Troubleshooting > Sync Thread credentials. On iPhone, the docs say to open the Thread integration and use Send credentials to phone.

If Apple Home or Google Home already owns the working Thread mesh, the Thread docs say to import those credentials into Home Assistant first, refresh the screen, and then Make preferred network. That is the moment when many "checking network connectivity" stalls are really "the phone and Home Assistant never agreed on the same Thread network."

4. Treat "preferred network" as helpful, not absolute

This nuance matters more than most people realize. Home Assistant's Thread docs explicitly say the preferred-network function is not completely implemented yet. In particular, when adding Matter devices through the companion apps, the mobile device's preferred network can still be used.

That means you can set the right network in Home Assistant and still fail if the phone is holding stale Apple, Google, or old Home Assistant Thread credentials. Current GitHub issues make that limitation concrete: one April 2026 issue reports that Thread credentials could not be sent to an iPhone at all, and another older but still relevant issue describes multiple Thread credentials on iOS causing the app to use the wrong one. If you have bounced between Apple-created, Google-created, and Home Assistant-created Thread networks, assume stale credentials are in play until you prove otherwise.

5. Turn on IPv6 where Home Assistant actually runs

Home Assistant's Thread docs say Thread is an IPv6-only protocol. The Matter docs add that Matter depends on local IPv6 and mDNS moving freely through the network. This is the part many otherwise strong home networks get wrong: the router can be "modern," the phone can have Wi-Fi, and the app can still be doomed because the actual Home Assistant host has IPv6 disabled or half-working.

The Matter docs say there is no requirement for an IPv6-enabled internet connection or DHCPv6 server, but they also say IPv6 support has to be enabled on Home Assistant and recommend using Automatic if you are unsure. The current GitHub issue about adding an IPv6 pre-check exists because users can still set up Matter even when the selected Home Assistant interface has no usable IPv6 path at all.

If you run Home Assistant inside a VM, container, or custom Docker path, the Thread docs warn that the hypervisor, Docker daemon, host OS, virtual network, or router can each become the missing layer. Home Assistant's Matter docs also say Home Assistant OS is the supported path for Matter, while container or standalone Docker approaches are at your own risk. This is one of the clearest cases where the infrastructure choice in Home Assistant OS vs Docker changes the amount of pain you buy yourself.

6. Flatten the network until it works once

Home Assistant's Matter docs are unusually direct here: Matter is designed for regular residential network setups and may not integrate well with enterprise-style features like VLANs, multicast filtering, and malfunctioning IGMP snooping. They also say a router or access-point setting that tries to "optimize" multicast can actively hurt Matter discovery traffic.

For troubleshooting, use the simplest proof path first. Put the phone, Home Assistant, and the relevant Wi-Fi Matter device or Thread border router on the same ordinary LAN or VLAN. Disable guest isolation. If you use UniFi, Omada, Eero, or another mesh platform with multicast enhancement, client isolation, or aggressive optimization features, simplify before you conclude the accessory is bad. After the device pairs cleanly once, you can reintroduce segmentation deliberately, using the network-placement guidance in Should Home Assistant Live on Your Main Network or IoT VLAN?.

7. Only after the basics check out, inspect Thread channel and RF interference

If the device pairs once but onboarding is still unreliable or previously joined Thread devices go flaky, the official Thread docs say to inspect the Thread channel and 2.4 GHz interference. Thread shares spectrum with Wi-Fi and Bluetooth. The docs say channel 26 is least likely to experience Wi-Fi interference, with channel 25 also helping in many homes. They also call out repeated ChannelAccessFailure messages as a sign that the channel is too busy.

This matters, but it is usually not step one. A surprising number of "radio" complaints are still just wrong credentials, no local IPv6, or multicast blocked upstream.

A Recovery Sequence That Wastes the Least Time

If you want the shortest practical path instead of three hours of random retries, use this order:

  1. Update Home Assistant Core, Home Assistant OS, Matter Server, OTBR, and the companion app. Home Assistant's June 3, 2026 release notes specifically call out a built-in mDNS implementation from OpenThread that should help with a class of stubborn Thread connectivity problems.
  2. Confirm whether the accessory is Wi-Fi Matter or Matter over Thread.
  3. If it is Thread, sync or import the Thread credentials again and confirm which network Home Assistant and the phone are actually using.
  4. In Home Assistant, verify that the selected network interface has IPv6 enabled.
  5. Move the phone physically close to the device. If it is Wi-Fi Matter, make sure the phone is on the target 2.4 GHz Wi-Fi.
  6. Temporarily simplify the network so that the path is boring: same LAN or VLAN, no guest isolation, no multicast enhancement, no clever filtering.
  7. Retry using the manual numeric code if the QR-code flow keeps stalling. Home Assistant's Matter flow explicitly supports manual entry.
  8. Only after those checks, factory-reset the device and try again.

When Pairing in Apple or Google First Is the Pragmatic Move

If Apple Home or Google Home already owns the stable Thread network on the phone you are holding, pairing there first and then sharing the device to Home Assistant can be the cleanest move. Home Assistant supports multi-fabric Matter, so this is not architectural surrender. It is just a practical recognition that the phone's real credential state often matters more than the diagram in your head.

If you want the full controller-choice tradeoff, Tara already has that decision mapped out in Should You Pair Matter Devices to Home Assistant or Apple/Google First?. If your Thread path specifically relies on Apple TV or HomePod, pair this article with Can Apple TV or HomePod Be Your Thread Border Router for Home Assistant?.

Practical translation: use the Thread network that already works on the phone for commissioning, then simplify the overall architecture after the device is stable inside Home Assistant.

Tara's Take

The stable answer is not "buy one more radio" and it is not "reset the accessory until the app gives up." The stable answer is to make the network path boring: one known Wi-Fi or Thread path, the right credentials on the phone, IPv6 enabled where Home Assistant actually runs, and no unnecessary discovery filters in the middle.

That is also why Tara cares so much about local, supported, preconfigured setups. Matter is increasingly useful, but it still rewards discipline more than improvisation. If lights, locks, blinds, or alarms in a real house depend on the system, do not accept a pairing flow you cannot explain twice in a row.

If this stall is pushing you into bigger Thread, Matter, or network-design decisions, these guides cover the adjacent choices that usually create it.

FAQ

Does every Matter device need a Thread border router?

No. Only Matter devices that use Thread need a Thread border router. Wi-Fi Matter devices do not. Home Assistant's Matter docs tell you to look for both the Matter logo and either the Wi-Fi or Thread logo on the packaging.

Do I need IPv6 internet from my ISP for Matter to work in Home Assistant?

No. Home Assistant's Matter docs say there is no requirement for an IPv6-enabled internet connection or DHCPv6 server. The requirement is that local IPv6 support is enabled on Home Assistant and that local discovery traffic can move freely.

Why can the phone still use the wrong Thread network after I made one preferred in Home Assistant?

Because the Thread docs say preferred-network behavior is not completely implemented yet. During companion-app commissioning, the phone's preferred network can still win. That is why stale credentials on the phone keep causing trouble.

Is Home Assistant OS really the least painful path for Matter?

Usually yes. Home Assistant's Matter docs say Home Assistant OS is the supported path for Matter. Container, VM, and custom Docker setups can work, but they add more IPv6 and discovery layers to troubleshoot.

Does the checking-network-connectivity error usually mean the device is defective?

Usually no. It more often points to a local-network problem: wrong Wi-Fi or Thread path, missing phone credentials, disabled IPv6, multicast filtering, or virtualization issues between the phone, border router, and Home Assistant.