Tool · you run it, we never see it

The cause is usually two layers below where the error appears.

Of 47 Home Assistant threads where Matter or Thread commissioning failed, 24 reached a confirmed root cause. Fifteen of those — 62.5% — were in the network layer, not in Home Assistant, the device, or its firmware. Every one was invisible from inside Home Assistant.

This checks all of them in a few seconds, on the machine where they live.

curl -O https://hometechcompatibility.com/tools/matter-preflight.py
python3 matter-preflight.py

Download the script Read it first

Run it on the machine running Home Assistant — and if that is a virtual machine, run it on the host underneath too. One documented failure was caused by a setting on a Proxmox host that the VM inherited and could not see. Some checks read values that need root; without root they report CANNOT_DETERMINE rather than guessing.

1. Confirm you got the file we describe

shasum -a 256 matter-preflight.py

96179cbf0873cc12aced51e2f36e193d77b09cd93730ed96f2bac75f17ee266f

2. Read it

It is one file of plain Python with no dependencies, and every check carries a comment explaining the real failure it came from. Reading it is a reasonable thing to do and it will take you a few minutes.

3. Prove the two claims mechanically

The claims are: it never opens an outbound connection, and it never modifies anything. Both are asserted by a test that parses the script's source, so a code path that simply did not run this time cannot hide.

curl -O https://hometechcompatibility.com/tools/matter-preflight-verify.py
python3 matter-preflight-verify.py

7f52112d64fd441f175332ee8a702112cd08a86a1586c4530d4cfc29d1205f77

It fails on any outbound-capable import, a dynamic import of one, any socket call that transmits, any file write, any delete or rename, any permission change, shell=True, and any subprocess whose command cannot be established. Nine deliberate violations were injected during development to confirm it catches them; it caught all nine and passed the unmodified source. The command allowlist currently contains one entry: ip.

You can also just disconnect from the internet before running it. It will work.

• IPv6 switched off on the host. Matter has no IPv4 fallback. One case had it disabled in /etc/sysctl.d/99-proxmox.conf on the hypervisor; the symptom appeared inside Home Assistant as "address unreachable after PASE".
• No IPv6 inside the container. The Thread network, the radio and the device can all be healthy and commissioning will still stall.
• Forwarding on while accept_ra is not 2. The kernel then ignores the route your border router advertises. Docker turns forwarding on, so this pairing is common.
• Kernel ignoring the mesh route. Synology DSM on kernel 4.4 lacks accept_ra_rt_info_max_plen entirely and silently drops the advertised route.
• mDNS bound to the wrong interface, or a stale Thread prefix. On a multi-homed host the responder picks the default-route interface, which is often the wrong one.

It makes no changes, so it cannot break anything — and it cannot repair anything either. It prints what is wrong and the command that would change it, and leaves the decision to you.

It reports three states, not two: PASS, FAIL, and CANNOT_DETERMINE. That third one matters. "We could not look" and "we looked and found nothing wrong" are different answers, and merging them is how a diagnostic tool starts lying. A check whose input is unreadable never reports a pass.

Status: early. The logic is covered by 16 synthetic cases and the read-only and offline properties by the test above, but it has not yet been run against a live host that is actually failing. If it gets your case wrong, that is worth telling us — a wrong answer is more useful to fix than a missing feature.

Home Assistant added its own IPv6 repair check in core 2026.7, and it is explicitly a no-op on Container and standalone Core installs. Those are exactly the setups where these failures happen, which is the gap this fills.

Already have an error message? Read it here first — it will tell you whether your problem is even in this layer.