Category: Matter & Thread

Direct answer: Confirm that Home Assistant knows the selected Thread network credentials, that the phone has the same credentials, and that IPv6 and local discovery work between Home Assistant, the phone, and the border router.

Symptoms

• Commissioning times out after scanning the Matter code.
• The app says a Thread border router is required even though one is running.
• Home Assistant and the phone prefer different Thread networks.

Prerequisites

Update Home Assistant and its Companion app, enable Bluetooth on the phone, place the device in pairing mode, and keep the phone on the same local Wi-Fi as the border router.

Diagnostic steps

1. Open Settings → Devices & services → Thread → Configure.
2. Identify the preferred network. Home Assistant can only prefer a network whose credentials it knows.
3. In the Companion app, use its Thread credential sync or send-credentials action for your platform.
4. Reopen the Thread panel and confirm Home Assistant and the phone reference the same network.
5. Check the OpenThread Border Router app status and logs.
6. Verify IPv6 works on the Home Assistant host, router, and any container or VM layer.
7. Return the device to pairing mode and retry nearby.

Verify the fix

The device should finish commissioning, appear under Matter, respond to a command, and remain reachable after several minutes.

Recovery and rollback

Do not delete Thread datasets or reset border routers as an early step. Those actions can strand existing devices. If retrying, remove only the failed partial device entry and follow the manufacturer’s pairing-mode instructions.

Prevention

Choose one preferred Thread network intentionally, keep credential copies synchronized, and document which border routers belong to it.

Video overview: understand Matter’s network requirements

Vaclav Chaloupka explains the moving parts behind Matter in Home Assistant and shows the commissioning flow. The overview is especially helpful for understanding why the phone, Home Assistant host, Thread border router, local IPv6 network, and shared credentials must all agree before a Matter-over-Thread device can join reliably.

Video: “Matter in Home Assistant: It is dead simple (if you know how — explained in the video)” by Vaclav Chaloupka. Embedded from the creator’s original YouTube upload.

Sources

• Home Assistant: Thread integration and troubleshooting
• Home Assistant: Matter integration

Last reviewed: September 4, 2026.

Related Troubliq guides

• Matter & Thread guides
• Start Here

Find your next troubleshooting path

• Matter and Thread hub
• Matter device pairs but becomes unavailable
• HomeKit device already paired

Use the related guide that matches the next confirmed layer of the failure. Avoid changing unrelated systems at the same time.

Detailed evidence checklist for Thread credentials are synced but Matter commissioning still fails in Home Assistant

Before another change, create a short incident record. Include the exact time the symptom appeared, what the system was doing, the last successful action, and every update or network change made during the previous day. Record the Home Assistant release, installation type, integration version, device model, firmware, connection method, current address, and relevant entity IDs. Screenshots are useful for visible states, but copy the exact error text because screenshots may crop the detail needed to search logs.

Compare the failing item with one known-good item that uses the same path. If both fail, move outward toward shared services such as the integration, coordinator, add-on, DNS, router, cloud account, or Home Assistant host. If only one fails, stay close to that device: power, signal, address, credentials, firmware, permissions, and configuration. This comparison prevents a single-device problem from turning into an unnecessary system-wide rebuild.

Network tests that prove the failing layer

Use tests in layers. Confirm the address is current in the router or DHCP server. Confirm the Home Assistant host or container resolves the same name and reaches the intended address. Then test the actual documented service, port, or protocol. A dashboard loading on a phone proves only the phone’s path. A successful ping proves basic reachability, not authentication, WebSocket upgrades, multicast discovery, API encryption, event subscriptions, or application permissions.

For segmented networks, document source VLAN, destination VLAN, direction, protocol, and port before editing a firewall rule. Test the smallest temporary exception and remove it if it did not help. Discovery traffic and control traffic may use different mechanisms. Seeing a device in discovery does not prove Home Assistant can maintain a working session.

Configuration comparison procedure

Export or photograph the current configuration without exposing secrets. Compare it with official documentation field by field: host, port, account, region, project, encryption setting, device identifier, and optional switches. Watch for trailing spaces, uppercase versus lowercase account names, obsolete hostnames, restored encryption keys, or an account belonging to the wrong home or region.

Use Reconfigure or Reauthenticate before deleting an integration. Preserve entity IDs and note every automation, dashboard, script, scene, or helper that refers to them. If replacement becomes necessary, take a backup and map old entities to replacements. That makes rollback controlled rather than leaving broken references.

Power, radio, and timing checks

Do not interpret every unavailable state as software failure. Low-voltage devices may stay partly online while unstable power causes resets. Battery devices sleep and report on their own schedule. Wi-Fi and Bluetooth devices can associate yet fail at the application layer. Zigbee and Z-Wave devices depend on routes, radio conditions, and powered repeaters. Match the test to the technology instead of repeatedly pressing Reload.

Allow enough time after each test. Cloud polling, sleepy devices, retained MQTT messages, mesh repair, Bluetooth advertisements, and DHCP changes do not update instantly. Define the expected interval, then wait through at least two normal cycles. If availability returns briefly, capture the next disconnect in logs instead of declaring success.

Log-reading workflow

Synchronize clocks and reproduce the problem once. Start with the first warning or error at that timestamp; later messages may be consequences. Group errors by layer: name resolution, timeout, refused connection, TLS certificate, unauthorized account, invalid token, missing permission, unsupported capability, malformed payload, device timeout, or rate limit. Each group suggests a different next action.

Turn debug logging off after reproduction. Large files consume storage and bury the event. Redact tokens, passwords, keys, email addresses, public addresses, precise locations, and unnecessary unique identifiers. Keep the unredacted copy private for comparison with later tests.

Safe change order

1. Correct time, power, cabling, or an obviously stale address.
2. Reload only the affected integration when documentation supports it.
3. Use Reconfigure or Reauthenticate without deleting the entry.
4. Restart only the affected device or add-on during a safe window.
5. Restart Home Assistant when several components share the symptom or a change requires it.
6. Update software after reading release notes and preserving rollback.
7. Delete, exclude, reset, or rebuild only after safer checks prove it necessary.

Post-repair validation

Verify both directions. Confirm Home Assistant receives a fresh state, send one harmless command, and confirm the physical response. Check the returned state, logbook, history, and automation trace. Restart the affected component and verify automatic reconnection. During a maintenance window, confirm the repair survives a normal Home Assistant restart.

Monitor long enough to cover the original pattern. If failure occurred overnight, after DHCP renewal, deep sleep, or token expiry, a five-minute test is insufficient. Record the confirmed cause and exact corrective change. Remove temporary firewall rules, extra logging, duplicate test integrations, and unused credentials.

When to stop and escalate

Stop if hardware overheats, power is unstable, storage reports errors, a controller backup fails, credentials are rejected across services, or firmware may be damaged. Escalate with versions, timestamps, topology, redacted logs, the first meaningful error, and results of each safe test. Do not repeat destructive steps while waiting for help.

A strong report answers four questions: What still works? What exactly fails? What changed immediately beforehand? Which test most clearly separates the causes? Those answers help maintainers diagnose the correct layer.

Checkpoint 1 — preferred Thread dataset: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 1: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Verification checkpoint 2 focuses on phone credentials. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 2: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

For checkpoint 3, inspect Bluetooth handoff rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 3: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Checkpoint 4 — Matter server: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 4: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Verification checkpoint 5 focuses on border router. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 5: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

For checkpoint 6, inspect local IPv6 rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 6: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Checkpoint 7 — multicast discovery: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 7: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Verification checkpoint 8 focuses on fabric membership. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 8: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

For checkpoint 9, inspect multi-admin sharing rather than relying on the dashboard icon alone. Confirm the expected input, the system response and the returned state. Preserve the evidence, reverse any ineffective adjustment and move to the next checkpoint only after the current result is clear.Validation note 9: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Checkpoint 10 — commissioning logs: reproduce the original symptom once and record the result at the expected update interval. Compare it with the last known-good behavior. Keep the change only when this specific checkpoint improves the failure without creating a new warning; otherwise restore the previous value.Validation note 10: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Verification checkpoint 11 focuses on restart persistence. Observe the relevant state, event or log through two normal cycles and write down the timestamp. If the result is unchanged, undo the experimental change before testing another layer so the diagnosis remains controlled and reversible.Validation note 11: Recheck the symptom after a normal interval, compare it with the incident record, and document whether the latest change improved, worsened, or did not affect the failure. Restore the previous value when a test provides no benefit so unrelated changes do not accumulate.

Map the commissioning path before resetting the device

Matter commissioning can involve the phone, Home Assistant Companion app, Matter server, border router, Thread credentials, Bluetooth and the local IPv6 network. Identify which component owns the preferred Thread network and whether the phone has received the same operational dataset. Seeing credentials in one interface does not prove that the commissioning phone, Matter server and border router are using the same dataset.

Confirm Bluetooth is enabled for the initial handoff, the phone is on the intended LAN and required app permissions are granted. Keep the phone and device near the border router during the test. Do not disable IPv6: Matter relies on IPv6 locally even when the internet connection is primarily IPv4.

Distinguish a Thread attachment failure from a fabric failure

If commissioning fails before the device joins Thread, examine border-router availability, dataset consistency and radio reachability. If the device joins Thread but cannot be added to Home Assistant, examine Matter-server logs, fabric state, multicast reachability and whether the device is already commissioned to another fabric. Multi-admin sharing should use the existing ecosystem’s share flow; repeatedly factory-resetting a working device can create stale entries without repairing the network.

On segmented networks, confirm the phone, Home Assistant, Matter server and border-router discovery traffic can cross only the required trusted boundaries. Avoid broad firewall exceptions. Capture the timestamp of one commissioning attempt and align the Companion app, Matter server and border-router logs.

Verify a durable Matter repair

• The device appears once on the intended Matter fabric.
• The Matter server reports the node as available after commissioning.
• Commands and state updates work after Bluetooth is turned off.
• The device survives a normal restart of Home Assistant and the Matter server.
• Thread diagnostics show attachment to the intended network.

If another ecosystem already controls the device, test its official multi-admin sharing procedure before erasing it. Record the device model, firmware, border-router model, Thread dataset source, Companion app platform and the precise commissioning stage that fails. Those facts determine whether the next investigation belongs in Thread transport, Matter fabric management or the vendor implementation.