Smart Home

Matter-over-Thread commissioning stuck

Split a stuck Matter commission into its two phases — BLE pairing (PASE) vs join-network and operational discovery (mDNS/CASE) — and fix the IPv6/VLAN causes behind each.

Problem summary

Matter commissioning is two phases with two different failure modes. Phase one is Bluetooth LE discovery + PASE from the setup code; phase two is joining the network (Thread via the border router, or Wi-Fi) then operational discovery over mDNS and CASE. BLE-phase failures are proximity/passcode/one-session-at-a-time; phase-two failures are IPv6 being blocked, mDNS not crossing a VLAN, or the Thread border router being unreachable. Matter requires IPv6 — but link-local is enough; it just must not be blocked.

Operator snapshotEvidence first

First proof

Note where it stalls: during Bluetooth pairing, or after, while 'connecting to network'.

Screen to open

dns-sd -B _matter._tcp (operational) / _matterc._udp (commissionable)

Expected signal

You can place the failure in phase one (BLE) or phase two (network/mDNS).

Stop boundary

Don't collapse the VLANs — reflect mDNS and stop blocking IPv6 instead.

Layer path

1Matter commissioning has two phases with different failure modes: (1) discovery + PASE over Bluetooth LE from the setup code, then (2) join the network (Thread via the border router, or Wi-Fi), operational discovery over mDNS (_matter._tcp), and CASE.

2BLE-phase failures are proximity, a wrong/expired setup code, Bluetooth off, or another controller already holding the single allowed PASE session.

3Phase-two failures are IPv6 being blocked, mDNS not crossing a VLAN, or — for Thread — the border router being unreachable.

4Matter requires IPv6, but the precise rule is that IPv6 must not be blocked; link-local IPv6 is sufficient on the same link, so a flat network often works even with ISP IPv6 'off'.

Runbook

Step-by-step runbook

Start here. Do each check in order, compare it to the expected result, and stop when the evidence explains the failure or the safe stop point applies.

Locate the failure phase

Check: Watch whether it stalls during Bluetooth or after, on the network step.

Expected result: You know whether to fix BLE or the network/mDNS path.

If not: If it never starts a Wi-Fi device, suspect a 2.4 GHz/band-steering issue.

Clear the BLE phase

Check: Commission close to the device, Bluetooth on, only one app, correct code.

Expected result: Phase-one PASE completes and it moves to joining the network.

If not: If a second controller is mid-commission, close it and restart.

Unblock what phase two needs

Check: Ensure IPv6 isn't blocked and mDNS reflects across any VLAN.

Expected result: Operational discovery (_matter._tcp) and CASE complete.

If not: Don't collapse VLANs — reflect mDNS and allow IPv6 instead.

Verify the Thread path (over-Thread devices)

Check: Confirm a border router is online and reachable.

Expected result: The device joins Thread and becomes discoverable.

If not: If not, resolve border-router fragmentation/reachability first.

Retry and confirm operational

Check: Re-commission, then confirm the device responds in the app.

Expected result: The device is commissioned and controllable.

If not: If it commissions but later drops, check mesh/range and multi-admin load.

Decision tree

If: Fails during Bluetooth pairing.

Then: BLE phase — proximity, code, Bluetooth, or a competing session.

Action: Move closer, verify the code/Bluetooth, and ensure only one app is commissioning.

If: Pairs over BLE then hangs 'connecting to network'.

Then: Phase two — IPv6 blocked, mDNS not crossing VLAN, or border router unreachable.

Action: Unblock IPv6, reflect mDNS, and confirm the Thread border router is online.

If: Works on a flat network but fails once segmented.

Then: VLAN is dropping IPv6/mDNS the protocol needs.

Action: Add mDNS reflection and allow IPv6 between the device VLAN and the controller/hub.

Safe stop: Don't collapse the VLANs — reflect mDNS and stop blocking IPv6 instead.

If: A Matter-over-Wi-Fi device won't even start.

Then: Almost always a 2.4 GHz-only radio and the phone/AP steering it to 5 GHz.

Action: Put the phone on 2.4 GHz (or split the SSID) during commissioning.

Evidence

Evidence table

Symptom	Evidence to collect	Likely layer	Next action
Stalls at the Bluetooth step.	Phone-to-device distance, the setup code, Bluetooth state, other open apps.	BLE / PASE phase	Re-try close up with Bluetooth on and a single commissioning app.
'Connecting to network' never finishes.	IPv6 state on the path; mDNS reflection across VLANs; border-router reachability.	Operational discovery / CASE	Unblock IPv6, reflect mDNS, confirm the border router is online.
Commissioned a plug with 'IPv6 disabled' but a Thread device fails.	Whether link-local IPv6 still exists vs IPv6 actually blocked at L2/L3.	IPv6 (link-local vs blocked)	Treat 'must not be blocked' as the rule; link-local suffices on one link.
Only fails after network segmentation.	mDNS reflector presence and inter-VLAN IPv6 rules.	VLAN / mDNS	Reflect mDNS and allow IPv6 between device and controller VLANs.

Reference

Commands and settings paths

Discover the Matter service over mDNS

dns-sd -B _matter._tcp (operational) / _matterc._udp (commissionable)

Where: From a Mac on the device's network/VLAN.

Expected: The device advertises and is listed.

Failure means: Nothing listed across a VLAN means mDNS isn't reflected.

Safe next step: Enable an mDNS reflector or commission on a single VLAN.

Confirm IPv6 reachability

ping6 <device-link-local%iface>

Where: From a computer on the same link as the device.

Expected: The device replies over IPv6.

Failure means: No reply means IPv6 is blocked or filtered on the path.

Safe next step: Stop blocking IPv6; link-local is enough on the same link.

Check the Thread border router (for Matter-over-Thread)

Confirm the hub shows 'Connected' / ping6 the border router

Where: In the ecosystem app and from the LAN.

Expected: The border router is online and reachable.

Failure means: An offline/unreachable border router blocks phase-two discovery.

Safe next step: Restore the border router; see /smart-home/no-thread-border-router-found.

Hardware boundary

Hardware and platform boundary

Change only when

Add an mDNS reflector-capable router/firewall (or keep the smart-home VLAN flat) when commissioning fails only after segmentation, and a reliable Thread border router for over-Thread devices.

Evidence that matters

A router that supports mDNS reflection and unblocked IPv6 across the smart-home VLAN, plus a healthy Thread border router for over-Thread accessories.

Evidence that does not matter

Forcing global/ISP IPv6 — Matter needs IPv6 unblocked, not a public IPv6 prefix; link-local suffices on one link.

Avoid

Collapsing VLANs to 'fix' commissioning (reflect mDNS instead) or running two controllers' commissioning at once.

Related tool

Use the linked tool to turn this runbook into a guided check for your exact setup.

Device setup troubleshooter

Last reviewed

2026-06-03 · Reviewed by HomeTechOps. Built from 2026-06 research verified against Google Home Developers' commissioning/discovery primer and Matter's IPv6 + mDNS requirements; the differentiator is splitting BLE-phase from CASE-phase failures and correcting the over-stated 'Matter needs ISP IPv6' claim to 'IPv6 must not be blocked; link-local suffices.'

Sources/assumptions

Assumes commissioning a Matter-over-Thread (or Matter-over-Wi-Fi) accessory with a controller app and, for Thread, a reachable border router.
Matter's IPv6 requirement is stated precisely: IPv6 must not be blocked; link-local IPv6 is sufficient for same-link devices — your ISP/router need not provide IPv6.
Commissioning uses link-local multicast (mDNS) and, for Thread, controller-to-border-router reachability — so VLAN segmentation needs mDNS reflection, not collapsed VLANs.

Source-backed checks

HomeTechOps turns official docs and conservative safety rules into a shorter runbook. These links are the source trail for the page direction.

Google Home Developers: Commissionable and Operational DiscoveryUsed for the two-phase Matter commissioning model (BLE + PASE first, then join-network + mDNS operational discovery + CASE) that splits commissioning failures into BLE-phase vs CASE-phase.ndo.dev: Matter, Thread, and home network segmentationUsed for why Matter/Thread commissioning fails across VLANs (mDNS + IPv6 link-local) and the multi-homing / co-location fix for the controller.Connectivity Standards Alliance: Matter 1.5 (cameras, closures, energy)Used for the Matter version timeline (1.4 Nov 2024 to 1.5 Nov 2025 cameras/TLS to 1.5.1 Mar 2026) and Matter's IPv6 + mDNS requirements relevant to VLAN segmentation.

Diagnostic rule

1. Check the simplest signal first.
2. Change one thing at a time.
3. Confirm the layer (radio, IP, app) before deep config.
4. Stop when the evidence says the risk moved.

FAQ

Commissioning fails immediately, before it even joins the network — why?

That's the BLE phase. The controller finds the device over Bluetooth LE and runs PASE from the setup passcode, and only one PASE session can run at a time. Failures here are usually phone-to-device proximity, a mistyped/expired setup code, Bluetooth off, or another app/controller already holding a commissioning session. Move the phone next to the device, make sure Bluetooth is on, and don't run two apps' commissioning at once.

It pairs over Bluetooth but then hangs joining the network — what's wrong?

That's the second phase: the device joins Thread/Wi-Fi, then has to be found via mDNS (`_matter._tcp`) and complete CASE. The usual blockers are IPv6 being blocked on the path, mDNS not reflected across a VLAN, or — for Thread — the border router being unreachable. Confirm IPv6 isn't blocked, enable mDNS reflection if the device is on a separate VLAN, and verify the Thread border router is online. See Matter/Thread across VLANs.

Does Matter really need IPv6? My network is IPv4.

Matter needs IPv6, but the common 'you must enable IPv6 on your ISP/router' claim is over-stated. The requirement is that IPv6 must not be blocked — for devices on the same link, link-local IPv6 is sufficient, so a flat network often commissions fine even with 'IPv6 disabled' upstream. The failures happen when a firewall, VLAN, or switch actually drops IPv6/mDNS. Don't collapse your VLANs; reflect mDNS and stop blocking IPv6 instead.