A Thread device that appears stuck on the spinner is usually not frozen. It is working through a joining sequence that has more separate stages than a plain Wi-Fi setup does, and each stage can stall for its own reason: the Bluetooth handshake with your phone, the handover of network credentials, the radio-level process of finding and attaching to the mesh, and then becoming reachable from the rest of your home network. The screen shows one spinner for all of it. Before you cancel, it is worth working out which stage you are actually waiting on, because three of the four have named, checkable causes.
Versions this describes, and why that matters here
Everything below is checked against the documentation listed at the end of this article, all of it read on 2026-08-24: OpenThread's Thread Primer, Home Assistant's Thread integration page, and Home Assistant's Matter integration page.
Commissioning behavior changes with border router firmware, with controller app versions, and with the specification revision a given device was built against. A reader on a different app version or a newer border router will see different wording, a different number of stages on screen, and different retry behavior. Where this article does not name a menu or a toggle, that is deliberate. We did not read that screen in a vendor document, so we describe the destination instead of inventing a route.
Why there is no number in this article
The obvious question is how many seconds or minutes is too long. We are not going to give you one, because we have not measured it and any figure we invented would be worse than no figure at all. Commissioning time depends on the device, the controller, how far your phone is from both, how busy the radio channel is, and how many hops the device needs to reach a border router.
The useful replacement for a stopwatch is knowing what stage you are on. That is genuinely diagnosable, and it is what the rest of this covers.
The stages hiding behind one spinner
Stage one is a Bluetooth conversation between your phone and the device. The device advertises, your phone finds it, and a secure session is opened so credentials can be passed. Home Assistant's Matter documentation puts the role plainly: "Bluetooth is not used to control but to pair a device after unboxing or after factory resetting." If your phone cannot scan, this stage never starts, and the failure looks identical to a slow one. That is a phone-side problem rather than a Thread problem, and the same causes behind a Bluetooth setup that fails because of the phone apply here without modification.
Stage two is the credential handover. Thread network credentials work roughly the way a Wi-Fi password does: without them the device has nothing to join. Home Assistant's Thread documentation notes that border routers announce themselves on your network but that "these local announcements don't contain the network credentials." So the controller has to have the right credentials to give, and that is the step that quietly fails in a house with more than one vendor's ecosystem in it.
Stage three is the radio-level attach, and this is where the delay you can actually see comes from. OpenThread's primer describes discovery as a repeated broadcast across channels: "The device broadcasts an 802.15.4 Beacon Request on a specific Channel. In return, any Extender-Capable Devices (ECDs) in range broadcast a Beacon that contains their Thread network PAN ID, XPAN ID, and Network Name." Attaching afterward is not a single message either. The primer sets out a four-message exchange, "Parent Request, Parent Response, Child ID Request, and Child ID Response," and notes that "Every device, ECD or not, initially attaches to a Thread network as a Child (End Device)." A scan across multiple channels followed by a four-message negotiation is simply not instant, and a device that has to retry any part of it is not malfunctioning.
Stage four is becoming reachable from the rest of the house, which depends on the border router bridging the mesh onto your home network. If that bridge is not working, the device can be perfectly attached to the mesh and still show as failed in the app.
Four reasons a Thread device gets stuck pairing
No border router is available, or the one you have is offline. Home Assistant's Matter page states the requirement directly: Matter devices that only use Thread need to be "joined to Thread networks for which there is at least one Thread border router connected to the Home Assistant LAN." A device with nothing to join will spin until it gives up. If you are not sure how many you have or how many you need, how many Thread border routers you actually need is the place to start.
Your house has more than one Thread network and the device is trying to join the wrong one. Home Assistant's Thread documentation is blunt about how this happens: "each vendor forms their own Thread network when you start using their products," which leaves separate networks with separate credentials, and "devices can't roam between the Thread networks." A commissioning attempt that stalls in a house with two vendors' hubs is often a credential mismatch rather than a weak signal, and Thread networks that will not merge covers that split in full.
Multicast is being filtered somewhere between your phone and the border router. Home Assistant's Thread page names this as a specific cause of a phone failing to find the border router at all: "Some mesh Wi-Fi systems aggressively filter multicast traffic on Wi-Fi. This can prevent your phone from discovering the border router via mDNS." Its Matter page makes the same point about routers with traffic optimization features, warning that a setting "to 'optimize' multicast traffic can harm the (discovery) traffic from Matter devices." This one is invisible from the app, and it is the reason an identical device sets up in one house and not another.
The radio channel is congested. Home Assistant's Thread documentation notes that "Thread channels 11 through 24 can overlap with 2.4 GHz Wi-Fi," which causes repeated transmission failures. Repeated failures mean repeated retries, and repeated retries look exactly like a stuck spinner. The mechanics of that overlap, and how to see it, are the same ones described in Zigbee and Wi-Fi channel interference, because both sit in the same crowded band.
What to do while it is spinning
Do not walk away with the phone. The Bluetooth stage needs the phone near the device, and moving out of range mid-handshake ends the attempt.
Keep the app in the foreground and the screen awake. Commissioning is a live session, and a suspended app is a dropped session.
Do not power-cycle the device mid-attempt. You lose whatever progress the attach sequence made and start the whole sequence over.
If you do cancel, put the device back into pairing mode deliberately rather than retrying immediately. Home Assistant's Thread page notes that "Most devices only stay in pairing mode for a limited time. If it expires, reset the device to pairing mode and try again." A second attempt against a device whose window has already closed fails for a reason that has nothing to do with the first attempt, and the general procedure for that is in how to put a smart device into pairing mode.
What we deliberately did not tell you
We did not name the screen your app shows, the wording of its error, or the setting on your router that controls multicast, because those differ by vendor and by version and we did not read your specific one. The right place for the exact route is the manufacturer's own current support page for your model and app version, and if a page you find is more than a version or two old, treat its screenshots as a description of the destination rather than as directions.
FAQ
Is a Thread device that spins for several minutes broken?
Not on that evidence alone. The joining sequence involves a Bluetooth handshake, a credential handover, a multi-channel scan and a four-message attach, and any of them can retry. Duration on its own does not tell you which stage you are on, which is why the checks above are more useful than a stopwatch.
Why does the same device set up at a friend's house and not at mine?
The most common house-specific causes are a missing or offline border router, a second Thread network in the house holding different credentials, and multicast filtering on the router or mesh system, which Home Assistant names as a reason a phone cannot discover a border router at all.
Should I cancel and retry, or wait?
Waiting costs nothing while the app is still in the foreground and the phone is near the device. If you cancel, re-enter pairing mode on the device before the next attempt rather than tapping retry, because the device's pairing window may already have closed.
Does moving my phone closer actually help?
It helps the Bluetooth stage, which is the first one. It does not affect the radio attach to the mesh, which happens between the device and the nearest Thread node rather than between the device and your phone.
How do I know whether it is Thread or Wi-Fi that is failing?
If the failure happens before any credential handover, it is a phone and Bluetooth problem. If it happens after the app says it is adding the device to the network, the mesh and border router checks above are the relevant ones.
Sources referenced
- OpenThread, Thread Primer: Network Discovery and Joining (openthread.io), read 2026-08-24, for the Beacon Request and Beacon exchange and the four-message Parent Request / Parent Response / Child ID Request / Child ID Response attach sequence.
- Home Assistant, Thread integration documentation (home-assistant.io), read 2026-08-24, for per-vendor Thread networks and non-roaming devices, border router announcements not containing credentials, limited pairing windows, multicast filtering on mesh Wi-Fi blocking mDNS discovery of a border router, and Thread channels 11 through 24 overlapping 2.4 GHz Wi-Fi.
- Home Assistant, Matter integration documentation (home-assistant.io), read 2026-08-24, for Bluetooth being used to pair rather than control, the requirement for at least one border router on the LAN, and multicast optimization settings harming discovery traffic.