Matter QR / Pairing Code Not Working? How to Fix It
When a Matter QR or pairing code won't work, the problem is almost never the code itself—it's usually the network your phone is on, a device that's already linked to another hub, or a 15-minute commissioning window that has quietly expired. The fastest fix is to put your phone on the same 2.4 GHz Wi-Fi the device will use, factory-reset the device so it starts advertising again, and re-scan within a fresh setup window. Below we walk through every common cause in the order worth checking, and explain why each one trips up commissioning so you can fix it for good.
First, understand what the code actually does
A Matter setup code is not a password. It's a one-time onboarding credential the Connectivity Standards Alliance (CSA) defines so any controller—Apple Home, Google Home, Alexa, or SmartThings—can securely take ownership of a device. The QR code and the human-readable 11-digit numeric code contain the same information, so if your camera struggles, typing the digits does the exact same job.
During pairing, your phone discovers the device over Bluetooth LE (or, for some devices, an existing IP connection), uses the code to set up an encrypted session, then hands the device your Wi-Fi or Thread network credentials. Knowing this matters, because most "the code doesn't work" reports are really failures at one of those handoff stages—not a bad code.
Step-by-step: fix a code that won't pair
Work through these in order. Each step rules out one of the common failure points before you reach the rarer ones.
- 1Confirm your phone is on 2.4 GHz Wi-Fi and Bluetooth is on
- 2Factory-reset the device to reopen its commissioning window
- 3Re-scan the QR or type the 11-digit code in your hub’s app
- 4If it’s a Thread device, confirm you have a working border router
- 5Check whether the device is already commissioned elsewhere
1. Get your phone (and the device) onto the right network
This is the single most common cause. Most Matter-over-Wi-Fi devices only join 2.4 GHz networks, and commissioning can fail if your phone is sitting on the 5 GHz band of a combined network. Temporarily connect your phone to the 2.4 GHz SSID, or—if your router uses one merged name (band steering)—move close to the router so your phone lands on 2.4 GHz. Our guide to 2.4 GHz vs 5 GHz for smart home devices explains why this trips up so many setups.
Also confirm Bluetooth is enabled on your phone and that the app has Bluetooth and local-network permissions. Matter uses BLE for the initial discovery, so a disabled or un-permissioned Bluetooth stack makes the code look broken when the phone simply can't see the device.
2. Reset the device to reopen the commissioning window
By design, a Matter device only accepts commissioning for a limited time—the CSA spec sets the default window at around 15 minutes after power-on or reset. If the device has been powered on for a while, that window has closed and the code will be rejected even though it's perfectly valid. A factory reset (check the manufacturer's instructions—often a button hold or a power-cycle sequence) puts the device back into advertising mode and reopens the window.
3. Re-scan, or type the digits manually
If the camera won't lock onto the QR code, lighting and focus are usually to blame. Codes printed on glossy stickers, on curved surfaces, or already peeled and creased reflect badly. Wipe the lens, add even light, and hold steady—or just choose the "enter code manually" option and type the 11-digit number. The leading digits encode a version and discriminator; an easy mistake is reading a printed code that includes a hyphenated grouping and dropping a digit. Enter all 11.
Always start pairing from inside your hub's app—the add-a-Matter-device flow in Alexa, Google Home, or Apple Home—rather than your phone's generic camera. The system camera may show a Matter prompt, but routing through the app gives the cleanest result.
4. For Thread devices, confirm you have a border router
Many of the smallest Matter devices (locks, sensors, some bulbs) use Thread, not Wi-Fi. Thread devices can't join your network at all without a Thread border router—and if you don't have one, commissioning fails right after the code is accepted, which reads like a code problem. You may already own one: many recent smart speakers and hubs qualify, as we cover in Thread border routers you may already own.
5. Check whether the device is already commissioned
A Matter device that's already been added to one ecosystem won't accept a fresh setup code from a second app—its commissioning window is closed and it's "owned." You have two options: factory-reset it to start over, or use Matter multi-admin to generate a new, temporary pairing code from the first app and share the device with the second. This is the correct path if you want the device in, say, both Alexa and Apple Home.
Quick diagnosis by symptom
| What you see | Most likely cause | Fix |
|---|---|---|
| Camera won't recognize the QR code | Glare, focus, damaged sticker | Improve lighting or enter the 11-digit code manually |
| Code scans, then "unable to connect" | Phone on 5 GHz / wrong network | Join 2.4 GHz, disable VPN and guest network |
| "Device not found" / never discovered | Bluetooth off or window expired | Enable Bluetooth, factory-reset the device |
| Pairs partway, then fails | No Thread border router (Thread device) | Add or confirm a border router on the network |
| "Code already in use" / rejected outright | Already commissioned elsewhere | Reset, or share via multi-admin |
When the network itself is the problem
If you've reset the device and you're on the right band but pairing still stalls, look at the network. Overloaded 2.4 GHz channels, an unstable router, or a hub that keeps dropping off can all interrupt the credential handoff. Our pieces on building a stable smart-home Wi-Fi network and stabilizing a hub that keeps disconnecting cover the fixes that matter here—cleaner channels, a dedicated 2.4 GHz SSID, and a controller with a solid connection.
Frequently asked questions
Is the QR code different from the numeric pairing code?
No. They carry the same Matter onboarding payload—the QR is just a machine-readable version. If scanning fails, choose the manual-entry option in your app and type the 11-digit numeric code instead. Both commission the device identically.
Why does my Matter code say it's expired or already in use?
Matter devices only accept commissioning during a short window (about 15 minutes by default) and only from one controller at a time. "Expired" usually means the window closed—reset the device. "Already in use" usually means it's commissioned to another app—reset it or share it via multi-admin.
Do I need a hub or border router to pair a Matter device?
It depends on the device. Matter-over-Wi-Fi devices need a controller app and a 2.4 GHz network. Matter-over-Thread devices additionally need a Thread border router on your network. See whether you still need a hub for the full picture.
I lost the code—can I still add the device?
Often yes. Many devices print the code on the unit or its packaging, and most manufacturer apps can regenerate or display the setup code. If the device is already in one ecosystem, that app can issue a new code for multi-admin sharing.
