Matter QR Code Won't Scan? How to Fix Pairing Codes
When a Matter device won't pair because the QR code or numeric setup code won't scan, the fix is almost always one of three things: the camera can't get a clean read of the code, you're scanning it in the wrong app, or the code scans fine but commissioning fails for a network reason that gets blamed on the code. Work through those in order and most pairing failures clear in a few minutes — no factory reset required. This guide walks through each, starting with the fastest checks.
First, confirm what kind of code you're looking at
Matter devices ship with a single onboarding payload printed two ways: a QR code and an 11-digit numeric setup code (often shown with a small "Matter" logo or the words "Matter" / "scan to set up"). Both encode the same information. That's important, because it means you never actually need the QR image to work — the numeric code is a complete, equivalent backup. If the QR won't scan, typing the digits is the reliable fallback, not a lesser option.
The code may be printed on the device itself, on a sticker on the base or inside a battery door, or on a card in the box. Some products also display it on-screen or in the manufacturer's own app. Find all copies before you start — the printed one may be scratched while a duplicate on the manual is pristine.
Fix a QR code that won't scan
If the camera view opens but never locks onto the code, the reader isn't getting a clean, in-focus image. Run through these in order — they're listed fastest-first.
- 1Wipe the phone’s rear camera lens and the printed code
- 2Add soft, even light and kill glare and reflections
- 3Hold 4-8 inches away and let the camera focus
- 4Switch to typing the 11-digit numeric code by hand
- Clean both surfaces. A smudged rear lens is the single most common cause of a code that won't lock. Wipe the phone's camera and the printed code with a soft cloth.
- Fix the light. Scan in bright, indirect light. A glossy sticker under a ceiling light or lamp creates a hot spot of glare that blanks out part of the pattern. Tilt the device slightly, or move to diffuse daylight, so no reflection lands on the code.
- Get the distance and focus right. Very small codes need the camera close enough to resolve the squares but far enough to focus — roughly 4 to 8 inches. Hold steady for a second so autofocus can settle. Tap the code on your screen if your app lets you set focus manually.
- Watch for a damaged or curved code. A code on a battery-door curve, a wrinkled label, or one that's partly scratched may never resolve. This is exactly when the numeric code earns its place.
Enter the numeric setup code instead
Every Matter setup app accepts manual entry. When the QR won't cooperate, look for an option along the lines of "enter code manually," "set up without QR code," or "type setup code" on the scanning screen, then key in the 11 digits exactly as printed. This bypasses the camera entirely, so glare, focus, and lens smudges stop mattering.
Type carefully — the code is validated, so a single wrong digit produces an "invalid code" message that looks like a device fault but is just a typo. Double-check easily confused characters and re-enter rather than assuming the device is bad.
Make sure you're scanning in the right app
A Matter code has to be read by a Matter commissioner — the app for the ecosystem you're adding the device to. Scanning it with the stock phone camera, a generic QR app, or the wrong ecosystem's app will either do nothing or throw a confusing error.
Start the process by adding a device inside the platform you actually use:
- Apple Home: add an accessory in the Home app; recent iOS versions can also recognize a Matter code from the camera and hand it to Home.
- Google: start the add-device flow in the Google Home app.
- Amazon: begin from add a device in the Alexa app.
- SmartThings / Home Assistant: use each platform's own add-device flow.
A useful detail of Matter is multi-admin: once a device is commissioned into one ecosystem, that ecosystem can generate a fresh pairing code to share it with a second platform. If you're adding an already-paired device to a new app, don't reuse the original sticker — generate a new code from the first app instead.
The code scanned — but pairing still failed
If the app accepts the code and then stalls, times out, or reports it "can't connect," the code did its job and the problem is elsewhere. This is where most "QR not working" reports actually end up.
| Symptom after a good scan | Likely cause | What to try |
|---|---|---|
| "Couldn't find device" / commissioning times out | Bluetooth off, or phone too far from the device | Enable Bluetooth (Matter uses it to begin setup) and keep the phone within a few feet of the device |
| Stalls at "connecting to network" | Phone on 5 GHz, device needs 2.4 GHz | Put the phone on the 2.4 GHz network during setup; see our Wi-Fi bands guide |
| Thread device won't complete | No working Thread border router | Confirm a hub or speaker that acts as a border router is online — see whether you still need a hub |
| Fails near the end, repeatedly | Weak Wi-Fi where the device sits | Move it closer during setup, or improve coverage |
Two more platform-level checks: make sure Bluetooth and location permissions are granted to the setup app (Matter uses Bluetooth to hand off Wi-Fi or Thread credentials), and that your phone and the device are on the same network. If you've been through all of this and it still won't complete, our companion piece on why Matter devices won't pair covers the deeper network and firmware fixes.
Frequently asked questions
Why won't my phone camera scan the Matter QR code?
Most often it's a smudged lens, glare on a glossy sticker, or the code being too small to focus on. Wipe both surfaces, add even light, and hold 4-8 inches away. If it still won't read, type the 11-digit numeric code instead — it carries the same information.
Can I set up a Matter device without the QR code?
Yes. The 11-digit numeric setup code printed alongside the QR is a complete equivalent. Choose the manual-entry option in your setup app and type it in. There's no feature you lose by skipping the QR image.
I lost the code — can I still pair the device?
Sometimes. Check for duplicate copies on the device, the base, a battery door, and the manual. Many manufacturers can also surface the onboarding code through their own app or support channel. The code is unique to that unit, so a code from another device won't work.
The code scans but pairing fails — is the code bad?
No. Once the app accepts the code, the code has done its job. A failure after that is a network issue — Bluetooth turned off, the phone on 5 GHz, no Thread border router, or weak Wi-Fi where the device sits. Work through the table above.
