Home Assistant Matter and Thread: border routers, IPv6, VLANs and sharing devices

What Home Assistant does with Matter and Thread

Adding the Matter integration on Home Assistant OS installs the official Matter Server app, which does the Matter work. Home Assistant calls OS its recommended and only supported option. Running the Matter Server in Docker yourself isn’t supported, and Thread-based Matter devices need Home Assistant OS 10 or later.

New devices are added from the Companion app on a phone, not from a browser. On Android, install the full Companion app from the Play Store and allow Location all the time. On iPhone, use the latest Companion app.

The Thread integration appears when Home Assistant finds a border router. It stores each Thread network’s credentials, which work like a Wi-Fi password, and lets you pick a preferred network for new devices.

Thread border routers

Home Assistant can use border routers from other ecosystems, or be one itself.

• Separate networks: each maker’s border routers usually form their own Thread network with its own credentials. Devices can’t roam between them.
• Phone and border router: to add Thread devices from an Android phone, Home Assistant names Nest Hub (2nd gen) or Nest Wifi Pro; from an iPhone, HomePod mini or (2nd gen), or Apple TV 4K. Home Assistant’s own border router works with both.
• Connect ZBT-1: no longer made, but still updated. Home Assistant recommends its Zigbee firmware; Thread works but is still being refined, and points new buyers to ZBT-2.
• Multiprotocol (Zigbee and Thread on one radio) stays experimental and isn’t recommended.
• Placement: use the USB extension cable. USB 3 ports cause interference that can disrupt Zigbee and Thread.

Share Thread credentials with your phone

1. Android: in the Companion app, open Settings › Companion app › Troubleshooting.

2. Tap Sync Thread credentials.

3. iPhone: open Settings › Connectivity › Thread.

4. Tap Send credentials to phone in the preferred network box.

What it needs from your network

Home Assistant is unusually specific here. Matter is designed for ordinary home networks, and its docs warn about common “advanced” settings.

• IPv6: IPv6 multicast traffic must travel freely from your network to the Home Assistant host. Set IPv6 to Automatic or static in Settings › System › Network. No IPv6 internet connection or DHCPv6 server is needed.
• IPv6 routing for Thread: the host, your router and any Docker or hypervisor layer must route or forward IPv6.
• Multicast: router or access point settings that “optimise” multicast can break Matter discovery. Faulty IGMP snooping and multicast filtering cause trouble too.
• Mesh Wi-Fi: some mesh systems filter multicast, which can stop your phone finding the border router. Check their multicast, IGMP snooping and mDNS settings.
• VLANs: put Wi-Fi Matter devices and Thread border routers on the same VLAN as Home Assistant. Keep the network as simple and flat as possible.
• 2.4 GHz: the phone should be on the same 2.4 GHz network as the Wi-Fi Matter device while adding it.

Matter, and sharing devices with other ecosystems

Add a device that Apple Home or Google Home already controls

1. Make sure the Companion app is the latest version.

2. Open Settings › Connectivity › Matter and select Add device.

3. Select Yes. It’s already in use. and choose the controller, such as Google Home.

4. Follow the steps, then name the device, pick an area and select Finish.

Share a Home Assistant device with another controller

1. Open Settings › Connectivity › Matter › Devices and select the device.

2. Select Share device, then Share device again. No button press on the device is needed.

3. In the other app, scan the QR code or enter the sharing code.

4. To check, open the device’s three-dots menu and select Manage fabrics.

To remove another controller, delete it in Manage fabrics. For Apple Home, also remove the accessory from Apple’s Matter accessories list in iCloud Keychain.

Common problems and Home Assistant’s fixes

• “You need to use the Home Assistant Companion app”: devices can only be added from the phone app, not a browser.
• Android says Matter is unavailable: wait up to 24 hours for Google Play services to download its Matter modules. Then reinstall the Companion app or Google Home.
• Stuck at “Checking network connectivity”: hold the phone near the border router and the device. For Wi-Fi devices, use 2.4 GHz.
• “This device requires a border router”: set one up, or make Home Assistant one, and sync its Thread credentials to your phone.
• “Target node did not process the update file”: Apple border routers don’t forward the mDNS packets that Matter updates need. Add a non-Apple border router, or switch the Apple ones off for at least 30 minutes and retry.
• Devices randomly unavailable or commissioning errors: check the network rules above, especially VLANs, multicast settings and a flat topology.
• Need more detail: download diagnostics from the three-dots menu of the Matter integration or of the device.

Questions

Sources

• Home Assistant: Matter integration
• Home Assistant: Thread integration
• Home Assistant: OpenThread Border Router integration
• Home Assistant: Connect ZBT-1
• Google Home and Nest Help: Prepare your smart home for Matter
• Apple Support: Pair and manage your Matter accessories

Checked on 1 November 2026.

More device guides