Matter device won’t connect to Home Assistant: a step-by-step checklist

First, check the Matter logos on the box or in the manual: the device may use Wi‑Fi, Ethernet, or Thread. Matter is a control protocol, not a separate radio network. Thread devices need a Thread border router to connect the Thread mesh to your home IP network; Wi‑Fi devices need a stable connection to your local wireless network.

If Thread is configured in Home Assistant, open Settings → Devices & services → Thread and check which Thread network the phone and device use. For sharing Thread credentials or using a third-party border router, that network must be available on the LAN where Home Assistant runs. A Matter logo alone does not mean your server already has a Thread radio.

Add a new Matter device from Home Assistant Companion on a phone or tablet. The browser interface cannot complete commissioning for a new device. Update Companion, grant the permissions it needs for local network access and Bluetooth during setup, and keep the phone on your home Wi‑Fi network.

Prepare the device as described by its manufacturer and scan its Matter QR code. If scanning fails, enter the commissioning code manually. Keep the phone close during initial setup, and for Thread make sure the border router is online and connected to the network. If another ecosystem already set up the device, look for Matter sharing or multi-admin in that app instead of starting with a factory reset.

Matter communicates over IPv6 on the local network, and device discovery relies heavily on mDNS multicast. If the phone, Home Assistant, Wi‑Fi Matter device, or Thread border router is separated by VLANs, guest Wi‑Fi, or isolated access points, discovery packets may not get through. For diagnosis, temporarily put the relevant devices on one simple home network without client isolation.

Check that your router supports IPv6 on the local network, and temporarily disable features that block or aggressively optimize multicast. If commissioning works, restore network separation gradually and configure multicast forwarding for the segments that need to communicate. Do not expose Matter ports to the internet; commissioning devices should be reachable locally.

Matter lets controllers share a device across fabrics with multi-admin. If a sensor or light already works in Apple Home or Google Home, open its settings there and generate a code to add another controller. In Home Assistant, choose the option to add an existing Matter device and enter the new code. Once sharing is complete, both systems can control it.

If commissioning succeeds but the device later becomes unavailable, check its power, Wi‑Fi or Thread signal, and border router availability. Open the Matter network map in Home Assistant if it has topology data; it may reveal a weak connection or an offline node. For more detail, download device diagnostics from the Matter integration page. Capture them before changing the network or resetting the device so you can tell which change resolved the problem.