Matter commissioning fails with almost no useful error text. The app says it could not connect, or the code was not accepted, or it simply spins and gives up, and none of that tells you which of the six or seven distinct stages actually broke. The fix is to stop guessing and walk the stages in order.
The commissioning sequence, briefly
Knowing the sequence is most of the diagnosis, because each stage fails in a different way and needs a different fix.
- Discovery. A device that has never been commissioned advertises over Bluetooth Low Energy. A device already on Wi-Fi or Ethernet advertises over mDNS on the IP network instead.
- Passcode exchange. The commissioner reads the setup code from the QR label or the 11-digit numeric string and establishes an encrypted session proving both ends know it.
- Attestation. The commissioner checks the device’s certificate against the certification records it trusts.
- Operational credentials. The device is issued credentials for the fabric it is joining and stores them in a fabric slot.
- Network onboarding. For a Thread device the commissioner hands over the Thread credentials; for a Wi-Fi device it hands over the SSID and passphrase.
- Operational discovery. The device reappears over IP, is found by mDNS, and a secure operational session is established.
Record the last completed stage before changing anything. This separates setup-code and credential problems from the final network-discovery step.
Map the symptom to the stage
| Symptom | Most likely stage | First thing to check |
|---|---|---|
| Device never appears in the app at all | Discovery over BLE | Commissioning window, Bluetooth on the phone, distance |
| Code is rejected | Passcode exchange | Wrong code, or the device is already commissioned |
| ”Uncertified device” or attestation warning | Attestation | Controller’s certificate handling and its update state |
| Progress stops right after the code is accepted | Network onboarding | Thread credentials, or Wi-Fi band and security settings |
| Reaches the end, then times out | Operational discovery | Network reachability in stage 6 |
| Worked after setup, then became unavailable later | Steady-state operation | The separate device-offline guide |
Work down from whichever row matches. Do not factory reset yet; that resets the wrong layer in most of these cases and destroys any existing pairings.
Stage 1: the device never shows up
The commissioning window is time-limited. Follow the product’s documented pairing-mode procedure and start the app while that window is open; a blinking light alone does not establish that the device is accepting commissioning.
Other causes, in the order worth checking:
- Bluetooth is disabled, or the controller app lacks location or nearby-devices permission, which some phone platforms require before they will scan.
- The phone is too far from the device. BLE commissioning is a short-range operation; do the pairing in the same room, then install the device where it belongs.
- The device is already commissioned into a fabric. A commissioned device stops advertising over BLE entirely, which looks exactly like a dead device. This is the single most common false alarm.
Stage 2: the code is rejected
Setup codes are per-device and not transferable. The printed code is normally used for initial commissioning, including after a factory reset. For the usual multi-admin sharing flow, use a new pairing code generated by the existing controller.
This is the multi-admin flow, and it exists precisely so you do not have to reset. The first controller mints a short-lived code, the second controller consumes it, and the device ends up in both fabrics simultaneously. Factory resetting to add a second controller is the classic mistake: it removes the first pairing to create the second, and then people repeat the cycle wondering why the device keeps disappearing from the other app.
Stage 3: attestation warnings
Controllers validate a device’s certificate against the compliance records they trust. Failures show up as an “uncertified device” prompt, and there are three ordinary explanations: the product genuinely is not certified, the product is certified but the controller’s records are stale, or the device is a development or pre-production unit.
Update the controller first. If the warning persists, confirm the product’s certification and the manufacturer’s setup guidance before proceeding. A development device may require a documented commissioning procedure.
Stage 4: the fabric slot is full
Each fabric consumes capacity on the device. If the device has no free slots, another sharing attempt cannot complete until an unused fabric is removed. Phones belonging to the same ecosystem fabric do not each consume an additional slot.
Use an existing administrator’s fabric-management controls to inspect and remove obsolete entries before retiring a controller. Home Assistant documents a Manage fabrics menu for this purpose. A factory reset removes all pairings and should be a last resort when supported management paths cannot recover access. The multi-admin sharing guide explains the capacity and cleanup steps.
Stage 5: network onboarding stalls
For Thread devices, this stage hands over the Thread credentials, and it fails when the commissioner does not have any to hand over. Three variants:
- There is no border router on the network at all. Nothing can be onboarded onto a mesh that does not exist.
- There are border routers, but the commissioning controller cannot see their credentials. Home Assistant’s Thread integration lists the networks it knows about and marks a preferred one; if the list is empty or the preferred network is not the one your border routers formed, credentials will not be handed over correctly.
- There are two Thread networks. Each vendor’s border router formed its own, and the device lands on whichever one the commissioner chose, which may not be the one your controller can route to. Confirm the intended dataset and the phone’s available credentials; a matching network name alone is not proof. The Thread border router guide covers shared-network checks.
For Wi-Fi devices, the failures are more mundane and equally consistent:
- The device radio is 2.4 GHz only. On a single SSID that spans both bands, band steering can push the commissioner and the device apart at exactly the wrong moment. Follow the device and controller instructions for using a supported band during setup.
- The network is WPA3-only. Some devices need WPA2 or a transitional mode.
- The network has a captive portal or client isolation enabled. Both break commissioning outright.
Stage 6: operational discovery times out
After network onboarding, the commissioner must rediscover the device over IP and complete commissioning. Working local IPv6 and mDNS are required; client isolation, multicast filtering or an unsuitable VLAN layout can prevent that final exchange. Use IPv6 requirements for Matter and Thread for the host, discovery and routing checks. This network check applies to Wi-Fi Matter devices as well as Thread devices reached through a border router.
A device that already completed setup and responded to commands, then dropped later, needs a different diagnostic path. Continue with why Matter devices keep going offline for uptime, Thread network membership, sleep and subscription problems.
When a reset is actually right
Use a factory reset when the manufacturer’s recovery procedure calls for it or no supported administrator can recover the pairing state. Save the setup code first and expect to add the device to every desired fabric again. Resetting the device does not fix missing network credentials on a phone or a blocked discovery path.
Reducing the failure rate
Before retrying commissioning, check the setup prerequisites:
- Confirm a reachable border router and the intended Thread credentials for a Thread device.
- Complete the network checks linked from stage 6 before repeating the same pairing attempt.
- Put the device within reach of the phone and its intended Thread parent or Wi-Fi access point during setup.
- Keep a written record of which controllers hold a fabric on which devices, and unpair before decommissioning a controller.
If you are still deciding what to build on, Thread and Zigbee compared sets out where the two mesh technologies differ, including which failure modes each one is prone to.
