Device Integrations

Why Won't My Matter Device Pair With Home Assistant?

Matter device not pairing with Home Assistant? Check the Matter Server, phone Bluetooth, Wi-Fi band, IPv6, Thread border routers and pairing codes.

On this page
  1. Quick checklist
  2. 1. Check the Matter integration and Matter Server
  3. 2. Pair from the Companion app
  4. 3. Check the Wi-Fi network
  5. 4. Thread devices need a border router and credentials
  6. 5. The device is already in another ecosystem
  7. 6. Open the commissioning window
  8. 7. Update and check the logs
  9. What doesn’t help
  10. If a device is half-paired

When a Matter device won’t pair, the cause is usually the phone, the network, Thread or the pairing window. Work through the steps below in order. Most failures are fixed by the first three.

Quick checklist

  1. Pair from the Home Assistant Companion app on a phone, with Bluetooth on.
  2. Make sure the Matter integration and the Matter Server are running.
  3. Use a 2.4 GHz Wi-Fi network for Wi-Fi devices, on the same network as Home Assistant.
  4. Reset the device if its pairing window has closed, and use its QR code or 11-digit setup code.
  5. For Thread devices, confirm a border router and sync the phone’s Thread credentials.

1. Check the Matter integration and Matter Server

Home Assistant needs the Matter integration plus the Matter Server. On Home Assistant OS, the Matter Server runs as an add-on. Elsewhere, it runs in its own container, with host networking and IPv6 enabled.

Check Settings > Add-ons > Matter Server > Log for errors. Update Home Assistant, the Matter Server and the device’s firmware before you try again.

2. Pair from the Companion app

Commission Matter devices from the Home Assistant Companion app on iOS or Android, not from a desktop browser. The phone uses Bluetooth LE during pairing. Keep the phone within a few metres of the device, with Bluetooth on and any VPN off.

On Android, pairing uses the Matter module in Google Play Services. If pairing fails, update Google Play Services.

3. Check the Wi-Fi network

  • Use 2.4 GHz. Wi-Fi Matter devices need a 2.4 GHz network. They won’t join a network that only offers 5 GHz.
  • Keep the phone and Home Assistant on the same network as the device during pairing.
  • Enable IPv6. Matter uses IPv6 and mDNS, so IPv6 must be enabled on your router and on the Home Assistant host.
  • Watch for network isolation. VLANs, client or AP isolation and mDNS filtering commonly break Matter. If you use them, allow the devices and Home Assistant to reach each other.

4. Thread devices need a border router and credentials

Thread devices need a border router to reach your network. Common border routers include the OpenThread Border Router add-on for Home Assistant, Thread-capable Apple TV 4K models and HomePod mini, and Google Nest hubs and Nest Wifi Pro.

A border router doesn’t pass its credentials to your phone on its own. Sync them:

  • Android: use Sync Thread credentials in the Companion app’s troubleshooting options.
  • iOS: use Send credentials to phone in the Thread settings in Home Assistant.

If you have more than one separate Thread network, pairing can fail. Set Home Assistant’s preferred Thread network to the one your devices use.

5. The device is already in another ecosystem

If the device is already in Apple Home, Google Home or Alexa, generate a pairing code in that app and use it in Home Assistant. These pairing codes have a limited window, about 15 minutes, and the exact time varies. Start the Home Assistant pairing right after you create the code.

6. Open the commissioning window

New devices open a short pairing window after they power up. If that window closes before you finish, power-cycle the device or factory reset it. Then use the QR code or the 11-digit setup code printed on the device or its packaging.

7. Update and check the logs

Update Home Assistant, the Matter Server and the device firmware. If pairing still fails, check the Matter Server log for the error. The log shows which step failed, which helps you narrow the cause.

What doesn’t help

  • Reinstalling the app doesn’t reset device fabrics. Reset the device itself if you need a clean start.
  • Local control doesn’t need internet access once a device is paired. Pairing itself still needs Bluetooth on your phone.

If a device is half-paired

If a device shows up in Home Assistant but stops responding, or it won’t finish pairing, remove it, reset it, and pair it again. For the full removal steps, see how to delete a Matter device from Home Assistant.

For Thread and Matter devices, and the other protocols in your home, see adding and managing devices in Home Assistant.

The complete guide to device integrations

Adding and Managing Devices in Home Assistant: Integrations and Device Classes
Read the guide

Keep exploring

Guides from other topics

All topics →