Home Assistant / Troubleshooting
Home Assistant Cannot Add a Matter over Thread Device
Confirm the device is a Matter-over-Thread unit that was never commissioned, then separate the Companion commissioning entry, border-router visibility, Thread credentials, and the local network stage before changing anything.
By Andrey Tretyak · Sources last reviewed
Matter and Thread are different layers. Home Assistant runs the Matter controller in a separate Matter Server process, while Thread provides the radio transport and a Thread border router forwards packets rather than controlling the device. Commissioning starts from the phone over Bluetooth with the device nearby. This workflow follows the managed Matter Server app on Home Assistant OS; non-HAOS deployments have different support boundaries.[2][3]
Do not infer a cause from stage text such as Matter is unavailable or Checking network connectivity. First establish whether the device has already joined another Matter fabric, which Thread credentials are available to the phone, and whether local IPv6 multicast can flow. A previously commissioned device follows the documented sharing workflow rather than an automatic factory reset.[2][3]
Sections
Applicability
- Products
- Home Assistant
- Scope
- For Home Assistant Core 2026.9.x with the managed Matter Server app on Home Assistant OS, commissioning a Matter-over-Thread device through the Companion app where the device was never added to any fabric. Record the Core version separately from the OS, Matter Server, Companion app, and radio firmware versions. This page does not cover Matter-over-Wi-Fi, HomeKit-over-Thread, unsupported standalone Matter Server deployments, or a previously commissioned device that later becomes unavailable.[1][2]
- Last verified
Symptoms
- Adding a Matter-over-Thread device through the Companion app stalls or fails and the device never completes commissioning into Home Assistant. A device that paired successfully and later becomes unavailable is a different observation with its own future diagnosis.[2]
Quick diagnosis
Confirm a never-commissioned Matter-over-Thread device before reasoning about entry, routers, credentials, or network stages.
Confirm Matter-over-Thread and no prior fabric membership
Read the device packaging and any device information: the Matter logo with Thread transport, and no existing membership in any controller's fabric. Other transports, later outages, or an already-commissioned device each exit this page to their own path.[2][3]
Confirm the Companion commissioning entry and phone prerequisites
Confirm that the Companion app offers the commissioning entry. Then check the documented phone prerequisites: supported OS version, current Companion app, Bluetooth enabled, proximity to the device and border router, and location permission where the Android flow requires it. A missing entry is its own branch, not a reason to improvise another commissioning path.[2]
Do not reset, reconfigure networks, or invent thresholds
Do not factory-reset the device, disable firewalls globally, reset platform services, invent a Thread channel, or invent a timeout threshold before the failing stage is isolated. An already-commissioned device elsewhere selects the sharing workflow, never a default reset.[2][3]
Interactive troubleshooter
Your answers stay in this browser tab. The tool does not connect to your systems or send diagnostic results.
Guided check / step 1
Is this a never-commissioned Matter-over-Thread device failing to pair?
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]
Read the complete diagnostic tree without using the controls
- Is this a never-commissioned Matter-over-Thread device failing to pair?
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
- Does the device already belong to another controller's fabric?
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
- Is the Companion commissioning entry available with prerequisites met?
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
- Is a border router visible with known, synchronized credentials?
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
- Does commissioning stall at the network stage?
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
- Use the sharing workflow from the existing fabric
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 the missing entry prerequisite
Satisfy exactly the missing documented prerequisite: Companion app currency, OS version, Bluetooth state, proximity, or permission. Do not improvise an alternate commissioning path.[2]
- Provide a border router for the device network
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]
- Synchronize the Thread credentials to the phone
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 local IPv6 and multicast delivery layer by layer
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]
- Investigate the actual smart-home observation
Matter-over-Wi-Fi, HomeKit-over-Thread, standalone server deployments, and previously commissioned devices that later go unavailable each need their own diagnosis.[2]
- Collect a commissioning evidence packet
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]
Detailed diagnosis
1. Verify transport, history, and fabric state
Establish Matter-over-Thread transport, a never-commissioned history, and absence from every known fabric. Any other transport, a later outage, or existing membership elsewhere exits to the sharing branch or to a different diagnosis before any commissioning reasoning.[2]
2. Check the Companion commissioning entry and prerequisites
Confirm the commissioning entry is offered and the phone prerequisites hold: supported OS and current app versions, Bluetooth on, proximity to device and border router, and the documented permission state. The entry exists only in the Companion app, never in the browser.[2]
3. Check border-router visibility and known credentials separately
Confirm a Thread border router is visible for the device's network, then separately confirm which credentials are known and synchronized to the phone. Discovery announcements carry no credentials, and the preferred-network label alone never establishes the phone's selected credentials; resolve a documented mismatch before continuing.[3][4]
4. If commissioning stalls at the network stage, inspect local IPv6 and multicast
When credentials are delivered but commissioning stalls, inspect local IPv6 and multicast reachability layer by layer: host IPv6 setting, virtualization or container networking where applicable, access-point multicast and mDNS filtering, and available server and border-router logs. Working IPv6 internet is not a prerequisite; an absent warning is not proof every layer works.[2][3]
5. With no discriminating evidence, collect sanitized diagnostics
When prerequisites appear satisfied but nothing discriminates the failure, record the device model and firmware, phone OS and app versions, the reached stage, and the integration and device diagnostics with secrets redacted. Never convert a bare timeout into a proven interference or credentials diagnosis.[2]
Supported scenarios
These observations narrow the next investigation; they do not establish a unique cause.
The device, transport, or history does not match this page
Thread-only devices without Matter, Matter-over-Wi-Fi units, later outages of commissioned devices, or existing membership in another fabric each follow different documented paths. None of them is a commissioning failure of a fresh Matter-over-Thread device.[2][3]
How to check: Confirm transport logos, commissioning history, and fabric membership before any commissioning reasoning begins.[2]
The Companion commissioning entry or a phone prerequisite is missing
Without the offered commissioning entry or with an unmet phone prerequisite, the documented flow cannot start. The entry lives only in the Companion app and depends on OS version, app currency, Bluetooth, proximity, and documented permissions.[2]
How to check: Confirm whether the entry is offered and which documented prerequisite is unmet, without improvising an alternate commissioning path.[2]
No Thread border router is visible for the device network
A Thread border router connects the Thread mesh to other IP networks; for this Home Assistant Matter-over-Thread diagnosis it is required for the device to communicate with Home Assistant outside the Thread mesh. Visibility of a border router is checked in the Thread integration, not assumed from Matter support.[3][4]
How to check: Confirm border-router visibility for the device network in the Thread integration before any credentials reasoning.[3]
Thread credentials are unknown, unsynchronized, or mismatched
Discovery without known credentials cannot commission: the phone must hold the right Thread credentials, synchronized per the documented flow, and the preferred-network label alone never proves the phone selected them.[3]
How to check: Confirm which credentials are known, whether they reached the phone, and whether the phone's selected credentials match the target network.[3]
Commissioning stalls at the network stage on local IPv6 or multicast
With credentials delivered, a stall implicates local IPv6 or multicast delivery across host, virtualization, access-point, or border-router layers. Each layer is separately observable, and no single layer's silence proves another layer healthy.[2][3]
How to check: Confirm the stall stage, then inspect host IPv6, virtualization networking where applicable, access-point multicast behavior, and available server and border-router logs.[3]
Next actions and procedure boundaries
Already in another fabric: use the sharing workflow, never a default reset
When the device already belongs to another controller, add it through the documented sharing flow from that controller into Home Assistant's fabric, managing fabrics explicitly. Factory reset and removal from a fabric are destructive boundaries that can destroy existing control relationships, so they never serve as the default path here.[2]
Resolve the documented credential or preferred-network mismatch
Before changing anything
- Risk
- Changing credentials, preferred networks, radio firmware, channels, or host network settings affects Thread behavior for every device on the network, not only the failing one.[3]
- Safer check
- Confirm the exact credential mismatch with known-versus-selected evidence, record the current Thread networks and preferred setting, and confirm a configuration backup exists.[3]
- Expected result
- After the correction, the phone holds the target network credentials and commissioning proceeds past credential delivery; other Thread devices keep working.[3]
- Backup / recovery access
- Preserve the recorded Thread network list, preferred setting, and a Home Assistant backup before changing credentials or radio settings.[3]
- Rollback
- Restore the recorded preferred network and credential state if commissioning does not proceed, then re-collect the credential evidence before further changes.[3]
Synchronize the Thread credentials to the phone through the documented Companion flow, import or select the target network credentials per the Thread integration, and set the preferred network only where the credentials are known. For Matter commissioning through companion apps, the phone’s selected credentials govern; the Home Assistant preferred-network label alone does not direct commissioning. Verify the phone’s selected credentials match the target network before retrying commissioning.[3]
Network-stage stall: hand scoped environment evidence to the operator
Where the stall sits in local IPv6 or multicast delivery, hand the layer-by-layer evidence to the operator: host IPv6 setting, virtualization or container networking notes where applicable, access-point multicast and mDNS behavior, and the available server and border-router log excerpts. Environment network redesign stays outside this page.[2][3]
If no branch is proven: preserve the evidence
Record the device model and firmware, phone OS and app versions, Core version, the reached commissioning stage, and the integration and device diagnostics with all setup codes, datasets, and fabric secrets redacted. Send the sanitized evidence for upstream review; a bare timeout never becomes a proven cause.[2]
Warnings and boundaries
Editorial verification
The citations beside technical claims show their evidence. HomeLabFix chooses the diagnostic order and states where the evidence stops supporting a conclusion.
- Author and technical editor
- Andrey Tretyak
- Verification basis
- The cited vendor or project documentation plus the page-specific reasoning above.
- Hands-on status
- Direct reproduction is claimed only when a page explicitly describes the tested environment and result. “Last verified” means the cited evidence was reviewed on that date; it does not mean every procedure was reproduced.
- Correction path
- Report a source change, scope error, or reproducible contradiction.
Sources
Links were reviewed on 2026-09-13. Reachability and automated validation do not replace editorial verification of each claim.
- Home Assistant Core release records
Home Assistant project · Tier B · accessed 2026-09-08 - Matter integration and commissioning
Home Assistant project · Tier A · accessed 2026-09-08 - Thread integration and border routers
Home Assistant project · Tier A · accessed 2026-09-08 - OpenThread Border Router integration
Home Assistant project · Tier A · accessed 2026-09-08