Matter pairing explained
Six stages, one 88-bit code, and a different failure mode at every step. Knowing which stage you are stuck in is most of the fix.
What is actually in the pairing code#
The QR code is a compact binary payload, not a URL and not a serial number.
| Field | Size | What it does |
|---|---|---|
| Version | 3 bits | Payload format version |
| Vendor ID | 16 bits | Who made it |
| Product ID | 16 bits | Which product it is |
| Commissioning flow | 2 bits | Standard, user action required, or custom |
| Discovery capabilities | 8 bits | Which of BLE, SoftAP or on-network the device supports |
| Discriminator | 12 bits | Picks this device out of everything advertising nearby |
| Setup passcode | 27 bits | The secret that seeds the encrypted session |
Total: 88 bits. The manual code printed underneath is the same information in a shortened form, 11 digits for a standard on-network device or 21 digits when vendor and product IDs have to be included, with a check digit so a typo is caught before anything is sent.
Two consequences are worth internalizing.
The discriminator is why you can pair one bulb in a box of eight. Twelve bits gives 4,096 values. Your phone reads the discriminator from the code, then listens for the device advertising that exact value and ignores everything else.
The passcode is a real secret. It is the input to the cryptographic handshake, so anyone with a photo of the code can commission the device if a commissioning window is open. Setup passcodes also have a fixed list of disallowed trivial values, so a manufacturer cannot ship everything with 00000000.
The six stages, in order#
Discovery
Your phone or hub finds the device. Matter supports several ways in: Bluetooth LE advertising (the common case for a device that is not on any network yet), a Wi-Fi SoftAP the device hosts, on-network mDNS using the
_matterc._udpservice for a device already on your LAN, Wi-Fi public action frames added in Matter 1.4.2 which allow commissioning with no Bluetooth at all, and NFC from Matter 1.6. The commissioner matches on the discriminator from the code. Bluetooth here is a setup channel only: once the device is on the network, Matter stops using it, which is the point made in Bluetooth and BLE in the smart home.PASE: turn the passcode into an encrypted session
The commissioner and the device run SPAKE2+, a password-authenticated key exchange, using the 27-bit setup passcode. The result is an encrypted, mutually authenticated session called PASE. The important property is that the passcode is never transmitted, so someone sniffing the Bluetooth or Wi-Fi traffic learns nothing they can reuse.
Attestation: prove the device is what it claims
The commissioner sends a 32-byte nonce and asks the device to sign it. The device returns its device attestation certificate, which carries its vendor and product IDs, along with the intermediate certificate above it. That chain leads to a root published in the alliance's Distributed Compliance Ledger. The commissioner verifies the chain, checks the signature over the nonce, and validates the alliance-signed certification declaration that says this vendor and product combination is certified. This is the step that separates a certified device from an unknown one.
Credentials: give the device an identity on your fabric
The device generates an operational key pair. The private key never leaves the device, which is why no controller and no cloud can impersonate it later. It sends a certificate signing request; the commissioner installs the fabric's root certificate and issues a node operational certificate. The device now has an identity on this fabric and only this fabric, alongside any others it already holds. How Matter actually works explains what a fabric is and why the count matters.
Network credentials: put it on the network
Now, and only now, the device gets what it needs to reach your network: the Wi-Fi SSID and password, or the Thread operational dataset if it is a Thread device. The dataset comes from a Thread border router your ecosystem trusts, and if there is not one, this is where everything stops.
Operational discovery and CASE
The device joins the network, then advertises over DNS-SD as
_matter._tcp. The commissioner finds it again, this time as an IP host on your LAN, and opens a CASE session using the operational certificates both sides now hold. Bluetooth is dropped. Everything from here runs over IPv6 on your network.
Where it fails, stage by stage#
Matching the symptom to the stage is most of the diagnosis, because the fixes have nothing in common.
| Stage | What you see | Usual cause | What to do |
|---|---|---|---|
| Discovery | "No devices found", scanning forever | Device not in pairing mode, Bluetooth off, phone too far, or the device is already commissioned and no longer advertising | Factory reset the device, stand within a few feet, confirm Bluetooth permission for the app |
| PASE | "Incorrect code", fails right after scanning | Wrong or reused code, or the commissioning window has expired | Use the original label code for a first pairing; a shared code from another ecosystem is short lived |
| Attestation | "Cannot verify this accessory", "uncertified device" | Development hardware, an unlisted product, or a wrong clock on the commissioner | Check the date and time on your phone or hub. Apple and Google refuse uncertified devices; Home Assistant will pair them with a warning |
| Credentials | Fails near the end, sometimes as "already paired" | Fabric slots exhausted, usually from removals that never sent the remove-fabric command | Factory reset the device. See removing and re-pairing devices cleanly |
| Network credentials (Wi-Fi) | Progress bar stalls, device never joins | 2.4 GHz band steering, WPA3-only, hidden SSID, a captive portal, or guest network isolation | Split the bands temporarily. The device will not join 2.4 GHz Wi-Fi covers each case |
| Network credentials (Thread) | "Could not join network", or joins and is immediately unresponsive | No border router your ecosystem trusts, or the wrong Thread network offered | Confirm a compatible border router is online. Thread troubleshooting is the ordered version |
| Operational discovery | Reaches roughly 90 percent, then fails or times out | mDNS or IPv6 is broken between your phone and the device | The section below |
The failure that gets to 90 percent#
The most common non-obvious Matter pairing failure is at stage six, and it is almost never the device.
After the device joins the network, the commissioner has to find it again over DNS-SD. That is multicast traffic, and multicast is the first thing that breaks on a network that is otherwise fine. The usual culprits:
- The phone and the device are on different SSIDs or VLANs, so multicast never crosses. An IoT network is a good idea and it needs an mDNS reflector to work with Matter.
- Client isolation is on for the guest or IoT SSID, so devices cannot see each other at all.
- IGMP snooping or multicast filtering on a managed switch or an access point is dropping the traffic.
- IPv6 is disabled on the router. Matter is IPv6 only. Google Home in particular requires IPv6 to be enabled for Matter to work reliably.
The network setup a smart home wants covers how to build this correctly the first time, and Matter pairing fails: full diagnosis walks the whole tree in likelihood order.
Adding a second ecosystem#
The second pairing is the same six stages against a different fabric, with one change at the start. The controller that already owns the device opens a commissioning window, which generates a fresh, short-lived setup code. You use that code, not the one on the label, in the second app. The device ends up with two sets of operational credentials and per-fabric access rules.
That short-lived code is the source of a common frustration: it expires, and it expires faster than most people finish reading the instructions. Generate it and use it immediately. Sharing a Matter device across ecosystems has the flow per platform.
NFC, and what changed in 1.6#
NFC has arrived in two steps, and they are frequently conflated.
Matter 1.4.1 (May 2025) put the onboarding payload on an NFC tag as a substitute for the printed QR code. Tapping the tag gave the phone the same 88 bits it would have read from the code. Bluetooth still carried the actual commissioning session.
Matter 1.6 (June 2026) carries the whole commissioning exchange over NFC. That is a genuinely different capability: a bulb can be commissioned while it is still in the box, before it has ever had power, because the NFC field powers the tag.
The catch is level three from the buying test. No consumer ecosystem has shipped NFC commissioning as of September 2026, and Home Assistant has said it will not implement it because it needs hardware access the platform does not have. Treat it as a future convenience, not a reason to choose a product.
What information is in a Matter QR code?
An 88-bit payload: a version field, the vendor ID, the product ID, the commissioning flow, the discovery capabilities the device supports, a 12-bit discriminator and a 27-bit setup passcode. It is not a link and it contains no account information. The printed manual code is the same data as 11 or 21 digits with a check digit.
Can I reuse a Matter pairing code?
The code on the label is reusable for a first-time pairing after a factory reset, so keep it. The code generated when you share a device with a second ecosystem is different: it is short lived and single use, and you have to generate a new one for each additional controller.
Why does Matter pairing need Bluetooth?
Because a device that is not yet on any network needs some way to be reached. Bluetooth LE is the common answer, and Matter drops it as soon as the device is on Wi-Fi or Thread. Matter 1.4.2 added Wi-Fi commissioning with no Bluetooth, and Matter 1.6 added full NFC commissioning, but neither is widely implemented yet.
Why does pairing fail at 90 percent?
Almost always at operational discovery, the last stage, where the commissioner has to find the device again over DNS-SD on your network. Multicast traffic blocked between SSIDs or VLANs, client isolation, IGMP snooping and disabled IPv6 all produce this exact symptom. The device and the radio are usually fine.
Is the Matter setup code a security risk if someone sees it?
It is a secret worth protecting. The passcode seeds the handshake, so someone with the code can commission the device while a commissioning window is open. Once a device is fully commissioned and no window is open, a photographed code alone does not give an attacker control.
Does my device need to be certified to pair?
It depends on the controller. Attestation checks the device's certificate chain against the alliance's Distributed Compliance Ledger. Apple Home and Google Home refuse devices that fail. Home Assistant will pair an uncertified device after a warning, which is why development boards and DIY hardware work there and nowhere else.
Why do I have to pair a Matter device separately in every app?
Because each ecosystem is its own security domain with its own certificate authority, and credentials are never shared between them. Joint Fabric in Matter 1.6 is designed to replace that with one shared fabric and several administrators, but no consumer ecosystem has shipped it.
Primary sources
Specification and vendor documentation we checked while writing this page. Where a claim depends on firmware behaviour rather than a published spec, the page says so inline.