Let me start by saying that I have carefully read the Thread and Matter HA documentation (at least twice) and I am as sure as I can be that all pre-requisites are met. Here is an overview of my setup:
Single subnet network with full IPv4 and IPv6 addressing and connectivity both locally and to/from the Internet.
An existing Thread / Matter network consisting of 4 border routers (Apple TV 4K - ethernet connected, 3x HomePod mini all running xxOS 18.5).
Many HomeKit devices but currently only one Matter/Thread device; an Eve Weather running the latest available firmware (3.5). This device is working fine in HomeKit (connected via Thread/Matter).
My HA companion app devices are an iPad Pro M4 running iPadOS 18.6 and an iPhone 16 Pro running iOS 18.6. The HA companion app (latest version available on App Store) has local network and bluetooth access privileges enabled.
HA (core 2025.5.3) runs in a docker container hosted in a Centos10 ARM64 VM (4 CPU cores, 16 GB RAM). This VM also has full IPv4 and IPv6 connectivity. It is hosted on an Apple Mac mini M4 Pro (14 cores, 48 GB RAM, 10 GbE) which also has full IPv4 and IPv6 connectivity. The hypervisor is Parallels Desktop Pro. The VM uses bridged networking (so it appears as a separate device on the network). There are no firewalls running anywhere (host or VM).
Since I run HA in docker I am also running the HA matter server in a container following the instructions on GitHub. The server container runs in the same VM as the HA container. It appears to be running fine and appears to be connected to HA (I configured it as part of adding the matter integration to HA).
I have imported the existing thread network/credentials into HA both on the HA server and on my iPhone and iPad.
Using a bonjour browser I can see that the HA matter server has registered itself under _matter._tcp (Matter Operational Discovery and Communication) with the correct IP addresses.
When I use the Apple Home app to put the Eve Weather into pairing mode it appears in bonjour under _matter._udp (Matter Commissionable Node Discovery).
So far everything seems to be okay (at least to me).
In the HA companion app (on iPhone or iPad, same results) I then try to add a Matter device. It asks me for the pairing code, which I enter, and then when I tap āAdd deviceā it sits at the āAdding Matter deviceā screen with a slowly circling activity indicator forever (I have left it for up to 20 minutes before interrupting it). Same results every time. The app isnāt truly āhungā as I can tap the X in the top left of the āAdding deviceā screen and it cancels the operation.
I tried enabling debug logging in the HA matter integration for one of the attempts but it doesnāt seem to show anything interesting; no indication there of the attempt to add the device.
Iām kind of at a loss; any ideas on how to debug this? Or suggestions for making it work? Sadly the Matter server seems completely devoid of any kind of logging (as far as I can see anyway).
Correct, I do not have any other Matter devices in HA as yet.
I have the HA Thread integration installed and configured with the credentials of my existing Thread network (the one created by the 4 existing border routers). I do not have the HA Open Thread Border Router add-on installed since nothing in the instructions suggested that I need that. Also, my HA/matter servers/host does not have a thread radio (there should be no need for one for this to work since communication should all go via the existing border routers). Since I run a purely container based deployment I cannot anyway install regular add-ons.
Interestingly, a network trace of traffic to/from my iPhone during the period when it is trying to add the device does not show any traffic between my iPhone and either HA or the matter server. It is almost like the app is stuck trying to locate the device.
I have very similar setup, my thread border routers are Apple tvās and HomePod minis and I leverage them to put my matter over thread devices into pairing mode from Apple home app and then add them into my HA instance. Even have a couple Eve matter over thread light switches in my setup.
Under debugging/Thread I have credentials for my existing Thread network. There are two sets of such credentials which are identical to each other except for the Border Agent ID. Presumably these came from two of my four border routers. Not sure why I have two sets as opposed to 1 or 4. How many do you have showing there?
Itās good to hear that you have some Eve Matter devices working with HA and that the devices were initially set up via HomeKit.
As I explained, I cannot install the HA OBTR add-on. My installation is container based and so does not support add-ons. There is a container based version of the Matter server, which is what I am running, but no such equivalent for the HA OBTR. However, the OBTR should not be needed here as it (a) basically makes HA a border router, (b) it needs Thread radio hardware on the HA server and (c) AFAIK (I may be wrong) creates its own separate Thread network (probably a bad idea). Anyway, I cannot install it soā¦
Sorry Chris, apologies, itās complex so a lot to follow. I understand now.
As we know too well, LOL, Matter over Thread in many ways is still in its infancy.
With that said, and in my first hand experience, I have experienced the same as you, hanging in HA and Matter device in pairing mode never actually joining HA.
Hereās what worked for me to resolve it and get the Matter device into HA.
1- restart my iPhone
2- Restart my Mesh router network (used to be Orbi/now Eero)
3- restart my Apple border routers
4- then put Matter over Thread device in Apple Home into pairing mode again then I could successfully join it to HA.
Yes, it is complex and for sure this technology is far from mature right now. The thing I find frustrating is that there are so few tools/ways to debug issues. No logging in the matter server for example. Inadequate logging in the companion app (nothing shows in the logs there about what it is doing when it is trying to add the device.
I did as you suggested and did a rolling restart of all components including my iPhone. Sadly the end result was the same; HA app circles constantly when trying to add the device. Based on the diagnostics I have managed to capture this looks to me like a companion app issue (but I could well be wrong). The app does not seem to be doing any kind of relevant network traffic when it is supposedly trying to add the device. I donāt know how it can add the device if it is not sending anything relevant on the networkā¦ Iāve tried the app on my iPhone and iPad and also on my wifeās iPhone all with the same result.
Sigh. I really wanted to get this device added to HA.
Sorry, I just sorta of skimmed through this, but If I got this correct, you are not using OTBR, and you already have devices paired to Apple home and Apple TBRs. Since youāre not using OTBR, you donāt really need to worry about HA Thread integration.
I think you are doing everything correctly, but just to go over some things,
start by going to HA UI->Settings->Devices->Add Matter Device (doesnāt have to be Companion App) and choose something like āits already in useā, then for the controller pick Apple Home and you should see a pop up that says:
Find your device in Apple Home and open Accessory Settings.
Scroll all the way down and tap Turn On Pairing Mode.
You now see the setup code.
Paste the code you just received from the other controller.
If you are doing this and its just spinning, then my guess is that the Matter Server Container is not getting the commissionable node discovery which actually contains the letter ācā _matterc._udp. The Matter Logs should be showing something like ācommission_with_codeā followed by a lot of other things too.
These two questions please
1- on HA companion app
Go to settings, debugging, thread
A- scroll to bottom, there should be a button that states āsync thread credentialsā, please click that
B- step 2, Iām not home so I canāt see my thread network right now, but you should see the list of your Apple thread border routers. I think if you long press any of them, there is an option like āuse this thread border routerā. Please do that for one of them, after that, there will be a key like icon next to that border router.
2- on the network side, so you have mDNS enabled? we know ipv6 needs to be enabled but mDNS should be on too.
I agree on the troubleshooting being challenging and little to no logs. As we know, Apple home even worse cause there is zero logs.
But if I could do it all again, matter over thread definitely in infancy. And it takes the most ānursingā out of my entire smart home. I have like 13-15 devices or something.
Now I only buy Zigbee devices and use an SmLight with Ethernet connection for my Zigbee coordinator with Z2m integration in HA. And then with Apple home bridge integration, I send whatever Zigbee devices I want over to Apple home since I have my wife and
Yes Matter is whacked, this is the best way to add a matter device with HA though, I forgot to mention.
ā think you are doing everything correctly, but just to go over some things,
start by going to HA UI->Settings->Devices->Add Matter Device (doesnāt have to be Companion App) and choose something like āits already in useā, then for the controller pick Apple Home and you should see a pop up that saysā
Yes, @wmaker is correct. A Thread device only has to join the network once, after that it can be added to one or more Matter controllers.
If your device is on your [thread] network and part of a Matter fabric (eg Apple Home) then HA can be added as a second fabric using the pairing code under the Apple Home device settings. HA does not need to know any Thread credentials because the device already has them.
If your device is brand new (or factory reset), then you have to pick a fabric to add to first, and whichever app that fabric uses has to know the Thread credentials. Usually if you have Apple Home it works best to use that for the first fabric, because Apple, and then add to HA afterwards (I believe the docs suggest this).
Edited to add: if you have a problem with adding when āitās already in useā then itās usually a IPv6 and/or mDNS problem. Use the zeroconf browser in the HA network troubleshooting to make sure it sees the _matterc (commissioning) service announcements. This works best if your matter container uses āhostā networking, but I can be made to work with macvlan as well.
Thanks for the pointers. I have removed the Thread integration from my HA (not needed at present, so keep things simple). I also found how to view the matter server logs (it uses the container logging, obviously. doh!). Both my container (HA and matter-server) are using āhostā networking. I have verified that mDNS works fine on the Linux system hosting the containers and when in pairing mode the device shows up (under _matterc._udp.local) in the HA zeroconf browser. So that seems okay. However after restarting the matter server and then trying the pairing again this is what I see in the matter server logsā¦
2025-06-28 07:59:15.570 (MainThread) INFO [matter_server.server.stack] Initializing CHIP/Matter Logging...
2025-06-28 07:59:15.570 (MainThread) INFO [matter_server.server.stack] Initializing CHIP/Matter Controller Stack...
[1751093955.580470][1:1] CHIP:CTL: Setting attestation nonce to random value
[1751093955.580548][1:1] CHIP:CTL: Setting CSR nonce to random value
[1751093955.580867][1:1] CHIP:DL: ChipLinuxStorage::Init: Using KVS config file: /tmp/chip_kvs
[1751093955.581404][1:1] CHIP:DL: Wrote settings to /tmp/chip_kvs
[1751093955.581480][1:1] CHIP:DL: ChipLinuxStorage::Init: Using KVS config file: /data/chip_factory.ini
[1751093955.581519][1:1] CHIP:DL: ChipLinuxStorage::Init: Using KVS config file: /data/chip_config.ini
[1751093955.581531][1:1] CHIP:DL: ChipLinuxStorage::Init: Using KVS config file: /data/chip_counters.ini
[1751093955.581896][1:1] CHIP:DL: Wrote settings to /data/chip_counters.ini
[1751093955.581903][1:1] CHIP:DL: NVS set: chip-counters/reboot-count = 10 (0xA)
[1751093955.581976][1:1] CHIP:DL: Got Ethernet interface: enp0s5
[1751093955.581998][1:1] CHIP:DL: Found the primary Ethernet interface:enp0s5
[1751093955.582029][1:1] CHIP:DL: Failed to get WiFi interface
[1751093955.582033][1:1] CHIP:DL: Failed to reset WiFi statistic counts
2025-06-28 07:59:15.582 (MainThread) INFO [chip.storage] Initializing persistent storage from file: /data/chip.json
2025-06-28 07:59:15.582 (MainThread) INFO [chip.storage] Loading configuration from /data/chip.json...
2025-06-28 07:59:15.604 (MainThread) INFO [chip.CertificateAuthority] Loading certificate authorities from storage...
2025-06-28 07:59:15.604 (MainThread) INFO [chip.CertificateAuthority] New CertificateAuthority at index 1
2025-06-28 07:59:15.604 (MainThread) INFO [chip.CertificateAuthority] Loading fabric admins from storage...
2025-06-28 07:59:15.604 (MainThread) INFO [chip.FabricAdmin] New FabricAdmin: FabricId: 0x0000000000000001, VendorId = 0xFFF1
2025-06-28 07:59:15.604 (MainThread) INFO [matter_server.server.stack] CHIP Controller Stack initialized.
2025-06-28 07:59:15.604 (MainThread) INFO [matter_server.server.server] Starting the Matter Server...
2025-06-28 07:59:15.605 (MainThread) INFO [matter_server.server.helpers.paa_certificates] Skip fetching certificates (already fetched within the last 24h).
2025-06-28 07:59:15.605 (MainThread) INFO [chip.FabricAdmin] Allocating new controller with CaIndex: 1, FabricId: 0x0000000000000001, NodeId: 0x000000000001B669, CatTags: []
**2025-06-28 07:59:15.636 (Dummy-2) CHIP_ERROR [chip.native.DIS] Failed to advertise records: src/inet/UDPEndPointImplSockets.cpp:421: OS Error 0x02000065: Network is unreachable**
2025-06-28 07:59:15.638 (MainThread) INFO [matter_server.server.vendor_info] Loading vendor info from storage.
2025-06-28 07:59:15.639 (MainThread) INFO [matter_server.server.vendor_info] Loaded 327 vendors from storage.
2025-06-28 07:59:15.639 (MainThread) INFO [matter_server.server.vendor_info] Fetching the latest vendor info from DCL.
2025-06-28 07:59:15.795 (MainThread) INFO [matter_server.server.vendor_info] Fetched 326 vendors from DCL.
2025-06-28 07:59:15.795 (MainThread) INFO [matter_server.server.vendor_info] Saving vendor info to storage.
2025-06-28 07:59:15.796 (MainThread) INFO [matter_server.server.device_controller] Loaded 0 nodes from stored configuration
2025-06-28 07:59:15.799 (MainThread) INFO [matter_server.server.server] Matter Server successfully initialized.
2025-06-28 08:01:51.835 (MainThread) INFO [matter_server.server.device_controller] Starting Matter commissioning with code using Node ID 35.
**2025-06-28 08:02:21.841 (Dummy-2) CHIP_ERROR [chip.native.CTL] Discovery timed out**
2025-06-28 08:02:45.674 (Dummy-2) CHIP_ERROR [chip.native.EM] <<5 [E:45326i with Node: <0000000000000000, 0> S:0 M:34078560] (U) Msg Retransmission to 0:0000000000000000 failure (max retries:4)
2025-06-28 08:02:55.451 (Dummy-2) CHIP_ERROR [chip.native.SC] PASESession timed out while waiting for a response from the peer. Expected message type was 33
2025-06-28 08:03:47.452 (Dummy-2) CHIP_ERROR [chip.native.EM] <<5 [E:45327i with Node: <0000000000000000, 0> S:0 M:34078561] (U) Msg Retransmission to 0:0000000000000000 failure (max retries:4)
2025-06-28 08:03:59.063 (Dummy-2) CHIP_ERROR [chip.native.SC] PASESession timed out while waiting for a response from the peer. Expected message type was 33
2025-06-28 08:04:51.612 (Dummy-2) CHIP_ERROR [chip.native.EM] <<5 [E:45328i with Node: <0000000000000000, 0> S:0 M:34078562] (U) Msg Retransmission to 0:0000000000000000 failure (max retries:4)
2025-06-28 08:05:02.674 (Dummy-2) CHIP_ERROR [chip.native.SC] PASESession timed out while waiting for a response from the peer. Expected message type was 33
2025-06-28 08:05:56.318 (Dummy-2) CHIP_ERROR [chip.native.EM] <<5 [E:45329i with Node: <0000000000000000, 0> S:0 M:34078563] (U) Msg Retransmission to 0:0000000000000000 failure (max retries:4)
2025-06-28 08:06:06.285 (Dummy-2) CHIP_ERROR [chip.native.SC] PASESession timed out while waiting for a response from the peer. Expected message type was 33
and then this just repeats for a long time until it finally gives up. Two lines stand out to me as concerning (the āfailed to advertiseā and āDiscovery timed outā errors). Do you see similar lines in your log when things are working? I suspect that for some reason the matter-server (only) maybe has an issue with mDNS discovery (but that is just a guess).
So my problem is solved and the device successfully added (easily and quickly).
Problem is solved! Key things that led me to solve itā¦
Unless you have other (non HomeKit) Thread devices that need to be managed by a separate (HA created) thread network then you do NOT need the Thread integration installed in HA to add/control Matter devices.
The Matter server (in my case a container), and hence the hist where it runs, must have IPv6 routes that allow it to communicate with the Thread network (in my case this network is fd4b:d3ef:1efd::/64).
Item (2) here was what was stopping it working for me. it may be possible to create static routes for your Thread network with your border routers as the gateways but for me it was easier to:
Change IPv6 address allocation on my Centos 10 server (which hosts my HA and Matter server containers) to use fully Automatic address assignment (DHCP6 and SLAAC) and then to set up a DHCOv6 static reservation for the servers āfixedā IPv6 address so it always gets allocated a well known IPv6 address. It does also assign itself a SLAAC address (which is fine) but more importantly it uses the RAs from the border routers to automatically create routes to them. Once I had done that all was good and adding the device was quick and easy.
That reminds me, when using multiple TBRs on the same Thread network, the developers found a few cases where the linux kernel would flap routes it received from multiple TBRs and some times the routes became stale when a TBR went offline, etc. They came out with some recommendations for how to configure the linux kernels for some of this, but they also came up with some of their own kernel patches. Anyway, here is a link that may be of interest
Yes, I read that several times. While there is some useful tidbits in there I would question some of what they say as it seems incomplete, misguided or out of date. Interestingly they do not mention the most critical thing; that the Matter server host (whether macOS or Linux) must be set for automatic IPv6 address assignment (more specifically it must use SLAAC [though it can use SLAAC+DHCPv6 as well]. This is necessary to ensure that the host OS accepts and properly processes RAs from routers, specifically the thread border routers. This was the missing piece of the puzzle. What this means in practice is that for macOS IPv6 address assignment must be set to āAutomaticā and for recent Linux distros using Network Manager (recommended) it must be set to āAutomaticā (NOT āAutomatic [DHCPv6 only]ā). Without this the host will not have any routes to the thread network (via the border routers) and so Matter will not function.
