Home Assistant Cannot Add a Matter over Thread Device

Confirm Matter-over-Thread transport and a never-commissioned history. Other transports, later outages, and already-commissioned devices each exit to their own path.[2]

• Yes, fresh Matter-over-Thread pairing → Does the device already belong to another controller's fabric?
• No, a different observation → Investigate the actual smart-home observation

Check every known controller for existing membership. An existing fabric selects the sharing workflow, never a reset; only a fabric-free device continues into commissioning reasoning.[2]

• No, never added anywhere → Is the Companion commissioning entry available with prerequisites met?
• Yes, already in another fabric → Use the sharing workflow from the existing fabric
• Cannot confirm fabric history → Collect a commissioning evidence packet

Confirm the commissioning entry is offered in the Companion app with Bluetooth on, proximity to device and border router, and documented OS, app, and permission prerequisites met.[2]

• Yes, entry offered and prerequisites met → Is a border router visible with known, synchronized credentials?
• No, entry or a prerequisite is missing → Satisfy the missing entry prerequisite
• Cannot confirm the entry state → Collect a commissioning evidence packet

Confirm a Thread border router is visible for the device network and, separately, that the right credentials are known and synchronized to the phone. Discovery alone proves nothing about credentials, and the preferred label alone proves nothing about the phone's selection.[3]

• Yes, router visible and credentials known → Does commissioning stall at the network stage?
• No border router visible → Provide a border router for the device network
• Router visible but credentials unknown → Synchronize the Thread credentials to the phone
• Cannot confirm router or credentials → Collect a commissioning evidence packet

With router and credentials in place, determine whether the failure sits at the network delivery stage: local IPv6, multicast, and border-router reachability. Any other stall shape exits to evidence preservation.[2][3]

• Yes, stalls at the network stage → Inspect local IPv6 and multicast delivery layer by layer
• No, a different stall shape → Collect a commissioning evidence packet

Add the device through the documented sharing flow from its current controller into Home Assistant's fabric. Never factory-reset as the default path.[2]

Satisfy exactly the missing documented prerequisite: Companion app currency, OS version, Bluetooth state, proximity, or permission. Do not improvise an alternate commissioning path.[2]

Set up a Thread border router covering the device: a Home Assistant radio with the border-router app or a documented third-party router nearby. Re-check visibility in the Thread integration afterwards.[3][4]

Import or synchronize the target network credentials to the phone through the documented Companion flow and confirm the phone's selected credentials match the target network before retrying.[3]

Inspect host IPv6, virtualization or container networking where applicable, access-point multicast and mDNS behavior, and available server and border-router logs. Working IPv6 internet is not required; environment redesign stays out of scope.[3]

Matter-over-Wi-Fi, HomeKit-over-Thread, standalone server deployments, and previously commissioned devices that later go unavailable each need their own diagnosis.[2]

Preserve the device model and firmware, phone OS and app versions, Core version, the reached stage, and the integration and device diagnostics with all secrets redacted. Send the sanitized evidence for upstream review.[2]