You bought a new Matter accessory. You open the Apple Home app, the Google Home app, or Alexa, and you tap to add a device. The app opens your camera. You point it at the QR code on the device or its box. Nothing happens. You move the phone closer. Still nothing. You give up and try the manual code entry instead, and the device pairs in twenty seconds. Why did the QR code refuse to scan?
What the QR code actually contains
A Matter setup QR code encodes a specific payload with the device’s vendor ID, product ID, discriminator, setup passcode, and commissioning capabilities. The payload follows the Matter specification’s setup code format, which is different from a generic URL QR code and different from the HomeKit setup code format that came before it.
Most camera apps and generic QR scanners can read Matter QR codes (they look like normal QR codes) but only Matter-aware apps know what to do with the decoded payload. The camera in the Home app, the Google Home app, and the Alexa app all decode Matter codes natively. The phone’s built-in camera app generally does not.
Reason one: you are using the wrong camera
Some users start by trying to scan with the phone’s built-in camera, expecting the same handoff that works with Wi-Fi network QR codes or contact cards. Matter codes do not work this way on most phones. You have to be in the Add Device flow of a Matter controller app, with that app’s camera, for the scan to do anything.
If you are inside the right app and the code still does not scan, move on.
Reason two: the code is too small, too damaged, or too dim
Matter QR codes are sometimes printed very small on accessory bodies (especially smart plugs and bulbs), and the version printed on the box is often the only one that scans reliably. If you have lost the box, the small in-device code may be at the edge of what your camera can resolve.
Tips:
- Use the largest version of the code you have available, usually the one on the box or in the included quick-start card
- Shine a flashlight on it from the side to increase contrast
- Move the phone away rather than closer; cameras auto-focus better at the 4 to 6 inch range than at 2 inches
- Hold steady for two or three seconds; the QR decoder needs a clean frame, and motion blur is the most common reason a code does not register
Reason three: the controller is not ready to commission
The Matter controller in your app might be doing something internally that prevents it from accepting a new commission, even if the camera is active. Common causes:
- The controller is mid-firmware-update
- Another commission is already in progress from a different device on the same network
- The controller cannot reach the underlying transport (Thread, Wi-Fi) for the new device
- The home has multiple Matter controllers and only some of them are advertising commissioning support
Close the Add Device flow, restart the controller (HomePod, Echo, Nest Hub), wait a minute, and try again. This resolves a surprising number of cases.
Reason four: the device is already paired
Matter devices keep an internal record of every commission they have completed. If a device was previously paired (even to a different controller, even briefly), its QR code may have been invalidated. The setup passcode encoded in the QR can be a one-time-use value.
The fix is to factory reset the device. Each accessory has its own reset procedure, but the most common patterns:
- Smart bulbs: power-cycle 6 times in quick succession
- Smart plugs: hold the physical button for 10 to 15 seconds until LED flashes
- Thread-only devices like Eve or Nanoleaf: app-based reset via the manufacturer app, or button hold
After reset, the QR code is valid again.
Fall back to manual entry
Every Matter device has an 11 or 21 digit setup code that is functionally equivalent to the QR code. It is printed below or next to the QR code. Type it manually into the app. Manual entry bypasses the camera entirely and is more reliable when the QR code is damaged or hard to position.
Apple Home, Google Home, and Alexa all accept manual entry. Look for a small “More options” or “Enter code manually” link in the Add Device flow.
The Thread credential side
If your Matter device uses Thread (smart sensors, some bulbs, locks), the commission needs more than just the setup code. It needs Thread network credentials to actually join the mesh after commissioning. If you do not have a Thread border router on your network, the commission may scan the QR fine but then fail at the network join step.
Symptoms of this: the app accepts the QR code, the commission begins, and then it fails with an error like “could not join network” or “device unreachable”. The fix is to add a Thread border router (HomePod Mini, Apple TV 4K from 2022, second-gen Nest Hub, Eero with Thread) and retry.
The dual-controller problem
If you are trying to add the same device to a second Matter controller (for example, you already have it in Apple Home and now want it in Google Home), you need to use the multi-fabric pairing flow, not the original QR. Apple Home and Google Home each have a “Share with another app” or similar option that generates a new ephemeral pairing code. The original QR code is no longer valid for multi-fabric commissioning.
When the device has a real defect
If the QR code is large, clean, well-lit, you are using the right app, the device is factory reset, and you still cannot pair, the device’s BLE commissioning radio may be defective. BLE is used for the commissioning handshake before the device joins Wi-Fi or Thread. A defective BLE radio means the device never even sees the commissioning attempt.
This is rare but documented for several first-generation Matter products. Return for replacement; there is no user-side fix.
The numeric code that always works when QR fails
Every Matter QR code has a corresponding 11-digit numeric setup code printed next to it. When the scan refuses to cooperate, type the number manually. The keystroke takes thirty seconds and the result is identical. Saving the numeric code in a notes app before the QR sticker fades is a habit worth building because the QR codes on bulbs and small accessories tend to wear off within a year.
If even the numeric code fails to commission, the bulk of the diagnostic moves to network and controller readiness. The deeper picture is in our Thread commissioning guide for accessories that need a border router after the QR scan completes.
Related reading: calendar trigger guide.
