Matter Pairing Failures: A Systematic Fix List

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.

1. 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.
2. 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.
3. Attestation. The commissioner checks the device’s certificate against the certification records it trusts.
4. 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.
5. Operational credentials. The device is issued credentials for the fabric it is joining and stores them in a fabric slot.
6. Operational discovery. The device reappears over IP, is found by mDNS, and a secure operational session is established.

Stages 1, 4 and 6 are where nearly all failures live, and they are network problems rather than device problems.

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	IPv6, mDNS, and multicast across the LAN
Pairs, then goes unavailable within hours	Operational discovery	Multicast filtering, VLANs, or an absent border router

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, typically around fifteen minutes from power-on or from the reset button sequence. A device sitting in a box for a day is out of its window even though its light is blinking. Power-cycle it and start the app immediately.

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 label code works only for the first commissioning. To add an already-paired device to a second controller you need a new pairing code generated by the first controller, not the printed one.

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 and you trust the source of the hardware, most controllers offer an explicit override to continue. Treat that as a decision rather than a formality, because it is the step that would otherwise stop an unknown device from joining the fabric.

Stage 4: 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. Checking that every border router reports the same network is the highest-yield diagnostic in Thread, and the border router buying and placement guide covers how to consolidate them.

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. Temporarily exposing a 2.4 GHz-only SSID for commissioning solves a surprising share of these.
• 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 5: the fabric slot is full

Every fabric a device joins consumes a slot, and devices support a bounded number of them; the specification sets a floor and inexpensive hardware tends to sit on it. A device with all slots occupied will accept the pairing attempt and then fail to complete.

Slots leak. Wiping a controller, reinstalling a hub, or abandoning an ecosystem without unpairing first leaves a fabric occupying a slot on every device it ever touched, with no controller left alive to release it. There is no remote garbage collection for this. Remove fabrics you no longer use through their controllers before decommissioning those controllers, and when slots are already lost, a factory reset of the device is the only remaining cure. This is one of the few situations where a reset is genuinely the right answer.

Stage 6: it pairs, then vanishes

This is the most frustrating class and the most predictable. The device commissioned successfully, so the radio is fine and the credentials are fine. What broke is the ability of the controller to find it again over IP.

• IPv6 must work on the LAN. Matter’s operational discovery is IPv6-based. A network where IPv6 is disabled, or where router advertisements are filtered, will commission devices and then lose them.
• mDNS must cross whatever boundaries you built. Controller and device have to be able to exchange multicast discovery traffic. If they sit on different VLANs or different SSIDs, you need an mDNS reflector or repeater on the router, correctly scoped to those interfaces.
• Multicast filtering on access points. Many wireless APs drop or rate-limit multicast by default, and some convert it to unicast in ways that misbehave at scale. IGMP or MLD snooping misconfigured on a managed switch has the same effect.
• Client isolation. Guest-mode isolation between wireless clients silently breaks everything in this stage.
• The border router rebooted. A single border router taking a firmware update makes every Thread device unreachable until it returns. If that pattern matches your outages, the fix is a second border router on the same network rather than anything on the device.

A useful discriminator: if Wi-Fi Matter devices stay reachable while Thread ones drop, the problem is at the border router or in the mesh. If everything Matter drops together while ordinary devices are fine, the problem is IPv6 or multicast on the LAN. The layering behind that distinction is set out in how Matter, Thread and border routers fit together.

When a reset is actually right

Factory reset the device when, and only when, all fabric slots are occupied by controllers you no longer have, or when the device is in an unrecoverable state after a failed firmware update. Everything above this line is fixed elsewhere, and resetting first destroys working pairings while leaving the real fault in place.

Reducing the failure rate

Most commissioning pain is structural, not incidental. Four changes remove the majority of it permanently:

1. Run at least two border routers holding the same Thread credentials, so no single reboot takes the mesh offline.
2. Confirm IPv6 and multicast work across every network segment a controller or device sits on, before adding devices rather than after.
3. Add mains-powered Thread devices before battery sensors, so the mesh has relay capacity as it grows. The Thread mesh and border router sizer shows how thin the relay layer gets when a network is all sensors.
4. 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.