How to Add a Matter Device to Home Assistant
The guide covers Wi-Fi and Thread prerequisites, companion app commissioning, multi-admin sharing, credential syncing, and common network failures.
The short version of how to add a Matter device to Home Assistant is: open the companion app on your phone, go to Settings > Matter > Add device, scan the QR code, wait. The long version is everything that has to be true before that works. This guide covers the prerequisites, the Wi-Fi and Thread steps, pulling in a device that already belongs to Apple Home or Google Home, and which failures are the network’s fault.
Who this is for, and who should stop here
You need Home Assistant OS. The Matter integration docs say running the Matter Server app on Home Assistant OS “is currently the only supported option”, and it is not supported on 32-bit platforms. Container installs can run the server image by hand, unsupported. Still choosing an install type? The sister site’s HAOS versus container comparison makes the case for HAOS, and Matter is one of the strongest reasons.
You also need a phone. Commissioning uses the companion app’s Bluetooth, and even if the host has an adapter, “Home Assistant does not use that adapter.”
The checklist before you scan anything
- IPv6 on the host. Settings > System > Network, set IPv6 to Automatic or static. The docs ask you to make sure “IPv6 (multicast) traffic travels freely from your network to the Home Assistant host.”
- The phone. Android 8.1 minimum, 12 or newer recommended, the full Play Store build, and Location set to “Allow all the time” so the app can read the Wi-Fi SSID. iPhone needs iOS 16 or newer.
- The right Wi-Fi. For a Wi-Fi device, the phone must be on the same 2.4 GHz network the device will join.
- The logos. The box needs the Matter logo plus a Wi-Fi or Thread logo. The docs put it bluntly: “Thread devices don’t necessarily support Matter.”
- Photograph the QR code. After a factory reset “you’ll need the QR code or numeric setup code to commission that device again.”
Adding a new Wi-Fi Matter device
On iPhone: Settings > Matter, Add device, “No, it’s new”, scan the QR code (or “More options” to type the 11-digit code), then Add to Home Assistant. An “uncertified accessory” prompt on a new product is fine to “Add Anyway”.
On Android: power the device up so it enters pairing mode. Android may offer a scan prompt on its own; pick Home Assistant. Otherwise go to Settings > Matter, Add device, Add Matter device, “No, it’s new”, then scan or choose “Setup without QR-code”. Either platform ends by asking for a name and an area.
Adding a Thread Matter device
A Thread device cannot reach your IP network on its own. It needs a border router, and your phone needs that border router’s Thread credentials before commissioning starts. The Matter docs list what qualifies: HomePod mini, HomePod (2nd gen) or Apple TV 4K; Nest Hub (2nd gen) or Nest Wi-Fi Pro; or Home Assistant’s own OpenThread Border Router add-on on a Connect ZBT-1, ZBT-2, SkyConnect or Yellow. Thread needs HAOS version 10 or later.
The Thread integration appears automatically once a border router is detected and stores the credentials “similar to a Wi-Fi password”. Getting them onto the phone is a menu item most people miss: in the app’s Thread settings, “Sync Thread credentials” on Android or “Send credentials to phone” on iPhone. If your only border router is Apple’s or Google’s, the same screen imports its credentials into Home Assistant.
One honest warning: the OTBR add-on docs say the radio must be on “a reliable link such as UART or SPI”; a network-attached radio will “leave stale routes in your network” when it drops, stranding every Thread device. The border router guide covers placement. With credentials on the phone, the steps are identical to Wi-Fi.
Adding a device that already lives in Apple Home or Google Home
No factory reset needed. Multi-admin lets one device hold several fabrics, so Home Assistant can control a bulb Apple Home still owns. In the app, Add device, then “Yes, it’s already in use”, pick the controller it belongs to and follow the prompts.
The other side has to hand over a code. In Google Home, per Google’s Matter help page, open the device, go to Settings > Linked Matter apps & services > Link apps & services, or tap “Use pairing code” or “Share with QR code” for a temporary code. Apple Home does the same from the accessory’s settings.
It works in reverse. Settings > Matter > Devices, pick the device, Share device, and Home Assistant produces a code for another platform without touching the hardware. The same page’s Manage fabrics menu is how you evict a controller later; the controller explainer covers what a fabric is.
Doing it without a phone
The Matter Server add-on docs list a ble_proxy option that will “expose the BLE proxy endpoint so the Home Assistant Matter integration can drive BLE commissioning through Home Assistant’s bluetooth stack”, replacing the older bluetooth_adapter_id setting. That covers the host’s own adapter or an ESPHome Bluetooth proxy. The integration page still documents the companion app as the supported route, so treat it as opt-in.
When it fails, it is usually the network
“Matter is unavailable” on Android means Google Play Services is still pulling the Matter modules, which can take up to 24 hours. Stuck at “Checking network connectivity” is almost always the phone on 5 GHz, or an old Android build. “Device requires a border router” means a Thread device with no reachable border router or credentials that never synced. Random failures point at blocked IPv6 or mDNS.
That last one bites homelab people, because the docs say Matter “may not integrate well with enterprise networking solutions like VLANs, Multicast filtering, and (malfunctioning) IGMP snooping.” IoT gear on a tagged VLAN behind mDNS reflection costs an evening; the sister site’s UniFi VLAN segmentation guide covers the multicast plumbing, and the pairing failures fix list walks each layer. Settings > Devices & services > Matter > Download diagnostics produces the file maintainers ask for.
When Matter is the wrong door
Philips Hue over Matter gives basic controls only; the native Hue integration keeps dynamic scenes and entertainment mode, both local. And Matter OTA updates “currently do not work for Thread devices on a Thread network with (any) Apple border routers”, so a HomePod-only mesh means firmware updates happen in the vendor app or not at all.
Add the device, name it, then leave the network alone. Most of the pain here is clever networking, not Matter.
Related across the network
- Zigbee vs Z-Wave vs Thread: Which Mesh to Build — homeassistanthq.com
- Home Assistant Hardware: What to Run It On — homeassistanthq.com
- Home Assistant OS vs Container: Which Install Method to Pick — homeassistanthq.com
- Zigbee Devices Going Unavailable: How to Fix It — homeassistanthq.com
- A $200 N100 Homelab: 11 Services, ~8W Idle, Low Maintenance — minilabhq.com
Related on this site
Sources
Related
How Many Thread Border Routers Do You Need?
A single Thread border router connects the mesh, two on the same network add resilience, and additional units should address verified coverage gaps.
Matter over Wi-Fi vs Thread: Power, Mesh, and Setup
Matter uses the same application layer over Wi-Fi and Thread, while power needs, mesh behavior, IPv6 setup, and border router requirements differ.
Matter Pairing Failures: A Systematic Fix List
A layer by layer fix list for Matter commissioning errors: Bluetooth handoff, IPv6 and mDNS discovery, Thread credentials, and exhausted fabric slots.