Matter pairing fails, and what is actually going wrong

The six stages, and what each failure looks like#

Commissioning runs in a fixed order. Where it stopped tells you what to fix, and timing is your main clue.

The most useful observation is when it failed. Instant means discovery or the code. At the end means credentials or network. Succeeds then dies means stage 6, which is a LAN problem, not a device problem, and is covered by a device shows as unresponsive.

The ordered diagnosis#

Work down this list. It is ordered by how often each cause turns out to be the real one.

1. Put your phone on the 2.4 GHz network

   Nearly all smart home devices are 2.4 GHz only. Controllers offer the network the phone is currently joined to, so a phone sitting on 5 GHz hands the device credentials for a band it has no radio for. On a combined SSID with band steering, you cannot choose which band the phone lands on.

   The test is to turn off the 5 GHz radio for ten minutes and pair. If that works, the permanent fix is separate SSIDs. If it does not, you have ruled out the most common cause in five minutes. The device will not join 2.4 GHz Wi-Fi has the rest.

2. Confirm Bluetooth is on and you are standing next to the device

   Stage 1 usually runs over Bluetooth LE, so the phone needs Bluetooth enabled, location permission on Android, and physical proximity. A device inside a metal enclosure, a recessed can or behind an appliance may be powered and still undiscoverable. Get within a couple of feet before concluding anything.

   If the app never finds it, check the device is still advertising. A factory-new device with no fabrics may advertise for up to 48 hours, but one powered on for a week may have stopped. Power cycle it, or press its pairing button.

3. Work out whether the device is already commissioned

   This is the cause people miss. Once any controller has commissioned a device, the code printed on the box stops working, because the factory passcode cannot be reused while the device belongs to a fabric.

   To add it somewhere else you need a fresh code from the controller that already owns it. Enhanced commissioning generates a short-lived passcode that the device itself never learns, which is why it is the safe path. The button lives in different places: Apple Home, device detail, "Turn On Pairing Mode". Google Home, device, gear icon, "Linked Matter apps and services". SmartThings, device, three dots, "Share with other services". Alexa, device settings, "Other Assistants and Apps". Home Assistant, Settings, Connectivity, Matter, device, "Share device". Sharing a Matter device across ecosystems has the full flow.

4. Check the commissioning window has not expired

   A commissioning window is deliberately short: a maximum of 900 seconds (15 minutes) and a minimum of 180 seconds, and it is single use. Generate a share code, go to find the second phone, take a call, and the window is closed and the code dead.

   The tell is a code rejected instantly, or a device that stopped appearing in the second app's scan. Do not retry it. Close the window, open a new one, and have the second app ready before you generate it.

5. Fix multicast and mDNS on your network

   Matter finds devices through DNS-SD over IPv6 multicast, both for commissionable devices (_matterc._udp) and for operational discovery afterwards (_matter._tcp). Anything that suppresses multicast kills discovery while leaving the device fully functional.

   The usual suspects are client isolation (also called AP isolation or guest mode), aggressive IGMP or MLD snooping, multicast-to-unicast conversion on mesh Wi-Fi systems, and VLAN boundaries with no mDNS reflector. The signature is a pairing that succeeds and then goes unresponsive. The network setup a smart home wants names the settings.

6. Put the controller, the phone and the device on the same subnet

   VLAN segmentation is good security practice and a reliable way to break commissioning. If your IoT SSID sits on a different VLAN from your phone, the controller cannot reach the device even when both are online. For the pairing attempt, move the phone onto the IoT VLAN, or bridge mDNS across the boundary in both directions with a reflector. Securing a smart home network explains how to keep segmentation without breaking discovery.

7. Suspect the fabric table when everything looks fine until the last moment

   Devices are required to support at least five fabrics. The SupportedFabrics attribute has a specified minimum of 5 and a maximum of 254, and constrained hardware really does ship with 5.

   The failure is badly signaled. The window opens, pairing appears to progress, and the credential step returns a table-full status at the end, which your app reports as "pairing failed" with no cause. Count what consumes slots: every ecosystem you have shared to, plus abandoned pairings, plus hubs you replaced without removing devices first. Apple Home consumes two, because it synchronizes accessories through iCloud Keychain, which needs a second fabric.

   The protocol has a remedy. RemoveFabric is not fabric-scoped, so an administrator on one fabric can evict another fabric's entry. Almost no consumer app exposes it; Home Assistant does, through its "manage fabrics" interface, which makes it the practical repair tool. Otherwise a factory reset clears the table. Removing and re-pairing devices cleanly prevents it recurring.

8. Read an attestation failure literally

   If your controller calls the accessory uncertified, stage 3 is telling you the certificate chain did not verify against the alliance ledger, or the certification declaration did not check out. That happens with engineering samples and development hardware carrying test certificates, with gray-market units, and occasionally with genuine products whose ledger entry is wrong.

   Controllers differ in strictness. Some refuse outright, some warn and let you continue at your own risk. Continuing is a judgment call: the device works, but its identity was never verified. A retail product that fails attestation is worth returning rather than working around, because it usually means the shipped firmware is not the firmware that was certified. Works with Matter versus Matter certified explains what the labels promise.

9. For Thread devices, confirm a border router first

   A Thread device cannot join a network that does not exist. Your ecosystem needs a border router it trusts, powered and reachable, before stage 5 can hand over an operational dataset. The most common hardware mistake is the Apple TV 4K 3rd generation: only the 128 GB Wi-Fi plus Ethernet model has a Thread radio.

   If a border router is present and pairing still fails at the end, check how many Thread networks you have, and check mDNS again, because a border router publishes records on behalf of sleeping devices. Thread devices dropping or split networks and the border router guide cover both.

10. Only now, factory reset the device

    A reset clears the fabric table and returns the device to advertising as factory-new. It is the correct fix for orphaned fabric slots and for a device left confused by a failed pairing. It is a poor first move, because it destroys the device's identity and its automations, and does nothing for band steering, multicast or an expired window.

Codes, and what they contain#

The QR payload is 88 bits: version, vendor ID, product ID, commissioning flow, discovery capabilities, a 12-bit discriminator and a 27-bit setup passcode. The manual code is 11 or 21 digits including a check digit.

A manual code rejected instantly is usually a transcription error caught by the check digit, so re-read it before blaming the device. The discriminator exists so a controller can pick your device out of several advertising at once, which is why pairing four identical bulbs in one session goes wrong. Do them one at a time. Matter pairing explained has the payload in full.

What does not help#

• Re-scanning the same QR code. If the device is already commissioned or the window closed, the code is dead and stays dead.
• Rebooting the router mid-pairing. It changes DHCP state and interrupts discovery. Reboot before you start, if at all.
• Buying a different brand of hub. Fabric exhaustion, blocked multicast and band steering all follow you to the new hub. See what Matter still cannot do for the gaps a purchase genuinely fixes.