Issue with Matter on self hosted Homey

Homey Self-Hosted Server
33

:white_check_mark: Solved: Homey SHS (Synology/Docker host mode) can’t add Matter-over-Thread devices (stuck on “Searching…”)

Hi All, I had the same issue, and it was very annoying after I’ve spent 100+ EUR on IKEA sensors :slight_smile: It took me a day but I’ve managed to find the solution, and now it’s working. Here are the details:

Symptoms

  • Homey Self-Hosted Server (SHS) runs on Synology DSM / Container Manager (Docker).

  • Matter-over-Thread devices:

    • Pair fine in Apple Home (HomePod minis as Thread border routers).

    • Pair fine when running SHS on a MacBook.

    • Fail only on Synology SHS: QR/code is accepted, then Homey keeps “searching” and eventually times out.

  • Matter-over-Wi-Fi devices work normally.

Root cause (what it turned out to be)

Homey SHS on the Synology could discover Matter devices via mDNS, but it could not reach the Thread devices’ IPv6 mesh addresses (ULA prefix like fd29:...) on TCP 5540 (Matter).
The Synology host was missing an IPv6 route to the Thread mesh prefix that macOS had automatically.

Analysis / How to confirm it

1) Check that Synology sees Matter services (discovery works)

SSH into Synology and run:

avahi-browse -rt _matter._tcp

You should see _matter._tcp endpoints and IPv6 addresses like fd29:... (Thread mesh ULA).

2) Compare IPv6 routes: MacBook vs Synology

On a Mac (where SHS worked), check IPv6 routes:

netstat -rn -f inet6 | egrep 'fd29|default'

In my case, macOS had a route like:

fd29:....../64  ->  fe80::xxxx%enX

Meaning: “send Thread mesh prefix traffic to this link-local next hop” (HomePod mini border router).

On Synology, check routes:

ip -6 route | egrep 'fd29|default'

No fd29:.../64 route existed, only default route.

3) Verify Homey container inherits the same routing (host mode)

My Homey container was running in host networking.
To inspect from inside Homey’s namespace, I used a netshoot container:

sudo docker run --rm -it --network container:<HOMEY_CONTAINER_ID> nicolaka/netshoot sh
ip -6 route

Then test connectivity to a Thread device:

nc -6 -vz -w 3 <fd29:...device-ipv6> 5540

Before the fix, it always timed out:

failed: Operation timed out

That’s why Homey pairing hung on “searching”.

:white_check_mark: Solution: Add the missing IPv6 route for the Thread mesh prefix

1) Ensure RA acceptance is enabled (good practice)

On Synology:

sudo sysctl net.ipv6.conf.eth0.accept_ra

Set to 2 (accept RAs even if forwarding is enabled):

sudo sysctl -w net.ipv6.conf.eth0.accept_ra=2
sudo sysctl -w net.ipv6.conf.all.accept_ra=2
sudo sysctl -w net.ipv6.conf.default.accept_ra=2

2) Add an IPv6 route for the Thread prefix via the border router (HomePod mini)

From the Mac route table (netstat -rn -f inet6) I found the next hop (link-local) used for fd29:.../64, e.g.:

fd29:.../64 -> fe80:...

Then on Synology I added the same route (without the %iface part):

sudo ip -6 route add fd29:.../64 via fe80:... dev eth0 metric 50

Confirm it exists:

ip -6 route | grep fd29

3) Re-test Matter reachability

Inside netshoot / Homey namespace:

nc -6 -vz -w 3 <fd29:...device-ipv6> 5540

After adding the route, Homey SHS could finally reach the device and pairing succeeded.

4) Pair again in Homey

After the route was added, I could successfully add Matter-over-Thread devices in Homey SHS.

Making it persistent (important!)

The route will disappear after reboot. Create a DSM boot-up task:

DSM → Control Panel → Task Scheduler → Create → Triggered Task → User-defined script
Event: Boot-up
User: root
Script example:

/sbin/sysctl -w net.ipv6.conf.all.accept_ra=2
/sbin/sysctl -w net.ipv6.conf.default.accept_ra=2
/sbin/sysctl -w net.ipv6.conf.eth0.accept_ra=2

/sbin/ip -6 route add fd29:.../64 via fe80:... dev eth0 metric 50 2>/dev/null || true

:warning: Note: if Apple switches the active Thread border router to another HomePod, the link-local next hop may change. For stability, consider:

  • disabling “Automatic Selection” for Home Hubs in Apple Home, or

  • updating the route if the active border router changes.

Summary

If SHS on Mac works but SHS on Synology hangs on “searching”, check IPv6 routes.
Missing fd29:.../64 route on Synology was the cause. Adding the route fixed Matter-over-Thread pairing in Homey SHS.

If it is too technical I recommend paste this solution into chatGPT and ask it to walk you through the process step by step. Hope it helps. Cheers, Pepe

4 Likes