Protocol
Thread/Matter or Z-Wave, controller, model, firmware, and integration version.
Thread or Z-Wave device will not join or stay paired
Use this flow when a smart-home device cannot finish commissioning or becomes unavailable after joining. Thread/Matter and Z-Wave need different evidence, controllers, and security boundaries.
Protect the network: do not share setup codes or security keys, delete device records, reset hardware, move radios, or change Thread/IPv6/multicast settings before the current state is documented.
What this flow is for
A Thread/Matter or Z-Wave device will not join, cannot complete interview/commissioning, or drops after it initially joins. The protocol and controller must be identified before troubleshooting.
First safe checks
- Record protocol, controller/border router, model, firmware, and failure stage.
- Confirm the controller service is online and the device is powered and in its pairing window.
- For Thread/Matter, check Bluetooth permissions, border-router reachability, IPv6, and multicast/mDNS evidence.
- For Z-Wave, start inclusion from the controller integration and keep the adapter in place.
- Run one permitted close-range test without deleting the existing record.
Best evidence
Capture this without credentials
Failure stage
Pairing, interview/commissioning, or later drop-off with timestamps and redacted error.
Controller path
Border-router or radio status and a close-range result without setup codes or security keys.
Likely causes
Most likely problem buckets
Wrong protocol/controller
The device is being added through the wrong integration, radio, or owner.
Pairing readiness
Power, pairing window, phone Bluetooth, or controller service is not ready.
Thread network path
IPv6, multicast/mDNS, or border-router reachability is incomplete.
Z-Wave radio state
Adapter placement, stale inclusion, interference, or an existing record blocks the join.
Next safe steps
Take one step at a time
ACT-SMART-020
Record protocol, controller, model, firmware, failure stage, and redacted error.
ACT-SMART-021
Confirm power, pairing window, controller service, and correct protocol integration.
ACT-SMART-022
Run one permitted close-range test and compare protocol-specific evidence.
ACT-SMART-023
Hand off before resets, exclusions, record deletion, radio moves, or network/security changes.
Best follow-up ask
Is this Thread/Matter or Z-Wave, which controller owns it, and does it fail during pairing or after it joins?
When to stop and hand off
Escalate before handling setup codes or security keys, deleting records, resetting hardware, moving radios, or changing channels, IPv6, or multicast.
Source provenance
Reviewed against official commissioning guidance
This flow uses Home Assistant’s Thread and Z-Wave troubleshooting guidance plus Thread Group commissioning guidance. Protocol-specific steps remain separate; the site does not collect credentials or keys.
Map the controller and device
Record the border router, Z-Wave radio, hub, device, and room relationship privately.
Open private discoveryContinue in support chat
The support assistant can identify the protocol and next safe question without accepting setup codes.
Open support chat