OTBR add-on injects fc00::/7 route, breaking host IPv6 ULA routing across local VLANs

[BorjaIglesias]

Describe the issue you are experiencing

When using Home Assistant on a segmented network with IPv6 Unique Local Addresses (ULA) configured for local VLANs (like fd10::/64 and fd30::/64), starting the OpenThread Border Router (OTBR) add-on completely breaks IPv6 communication between Home Assistant and devices on other local VLANs.

This causes integrations that rely on IPv6 across subnets (such as Matter Server or Matter Hub) to fail with peer-unresponsive errors, as return packets from Home Assistant never reach the physical router.

Root Cause: The OTBR agent forcibly injects a massive fc00::/7 route pointing to the wpan0 interface into the host's Linux kernel routing table. Because fc00::/7 encompasses all fd:: subnets, any return traffic that HA tries to send to a device on another local VLAN (e.g., a Google Nest Hub on fd30::/64) gets hijacked by the kernel. Since /7 is more specific than the default /0 gateway route, the traffic is routed into the wpan0 Thread mesh instead of the physical Ethernet interface, resulting in 100% packet loss.

What type of installation are you running?

Home Assistant OS

Which operating system are you running on?

Home Assistant Operating System

Which app are you reporting an issue with?

OpenThread Border Router

What is the version of the app?

3.0.2

Steps to reproduce the issue

1. Setup a network with multiple VLANs and IPv6 ULA enabled (e.g., HA on fd10::/64, client on fd30::/64).
2. Install and start the OpenThread Border Router add-on.
3. SSH into Home Assistant and check the routing table (ip -6 route). Note the fc00::/7 dev wpan0 entry.
4. Try to ping a device on the other VLAN from HA (ping fd30::xxxx). It will fail with 100% packet loss.
5. Stop the OTBR add-on or manually add a /64 static route via nmcli for the destination VLAN, and the ping will immediately succeed.

System Health information

System Information

version	core-2026.7.2
installation_type	Home Assistant OS
dev	false
hassio	true
docker	true
container_arch	amd64
user	root
virtualenv	false
python_version	3.14.6
os_name	Linux
os_version	6.18.37-haos
arch	x86_64
timezone	Europe/Madrid
config_dir	/config

Home Assistant Cloud

logged_in	false
can_reach_cert_server	ok
can_reach_cloud_auth	ok
can_reach_cloud	ok

HACS

GitHub API	ok
GitHub Content	ok
GitHub Web	ok
HACS Data	ok
GitHub API Calls Remaining	5000
Installed Version	2.0.5
Stage	running
Available Repositories	3459
Downloaded Repositories	17

Home Assistant Supervisor

host_os	Home Assistant OS 18.1
update_channel	stable
supervisor_version	supervisor-2026.07.3
agent_version	1.9.0
docker_version	29.5.3
disk_total	30.8 GB
disk_used	16.3 GB
nameservers	192.168.10.10
healthy	true
supported	true
host_connectivity	true
supervisor_connectivity	true
ntp_synchronized	true
virtualization	kvm
board	ova
supervisor_api	ok
version_api	ok
installed_addons	File editor (6.0.0), FTP (6.0.1), Let's Encrypt (6.4.0), Cloudflared (7.0.10), Advanced SSH & Web Terminal (24.0.1), Samba share (12.8.1), Home-Assistant-Matter-Hub (2.0.49), Matter Server (9.1.0), OpenThread Border Router (3.0.2)

Dashboards

dashboards	4
resources	9
views	13
mode	storage

Network Configuration

adapters	lo (disabled), enp0s18 (enabled, default, auto), hassio (disabled), docker0 (disabled), veth53621d7 (disabled), vethfd1d4dd (disabled), vethe7d1b3c (disabled), vethd48aeb0 (disabled), veth438b54e (disabled), vethb8313a0 (disabled), vethed6ea2b (disabled), wpan0 (disabled)
ipv4_addresses	lo (127.0.0.1/8), enp0s18 (192.168.10.100/24), hassio (172.30.32.1/23), docker0 (172.30.232.1/23), veth53621d7 (), vethfd1d4dd (), vethe7d1b3c (), vethd48aeb0 (), veth438b54e (), vethb8313a0 (), vethed6ea2b (), wpan0 ()
ipv6_addresses	lo (::1/128), enp0s18 (fd10::5322:56dd:5044:ad31/64, fe80::78c1:dce1:4af8:2068/64), hassio (fd0c:ac1e:2100::1/48, fe80::40e6:12ff:fee3:1ede/64), docker0 (fd12:f1a5:ccfd::1/64, fe80::942b:48ff:fede:4f9c/64), veth53621d7 (fe80::18ee:d9ff:fe8c:9863/64), vethfd1d4dd (fe80::4829:a8ff:fefc:55f4/64), vethe7d1b3c (fe80::98f4:72ff:fe94:74b1/64), vethd48aeb0 (fe80::c4cd:4eff:fedd:3bfd/64), veth438b54e (fe80::bc4f:4fff:fe3f:c9ed/64), vethb8313a0 (fe80::58f3:64ff:fe7f:8b08/64), vethed6ea2b (fe80::88ef:c8ff:fe67:22b7/64), wpan0 (fd05:2972:9e12::ff:fe00:fc10/64, fd05:2972:9e12::ff:fe00:fc38/64, fdbd:648b:9209:1:209:65f7:8206:f9ea/64, fd05:2972:9e12::ff:fe00:fc11/64, fd05:2972:9e12::ff:fe00:f000/64, fd05:2972:9e12:0:39c6:9f63:ad99:cc4d/64, fe80::488e:2549:9d27:63f1/64)
announce_addresses	192.168.10.100, fd10::5322:56dd:5044:ad31, fe80::78c1:dce1:4af8:2068

Recorder

oldest_recorder_run	4 de julio de 2026 a las 15:03
current_recorder_run	17 de julio de 2026 a las 10:07
estimated_db_size	1548.08 MiB
database_engine	sqlite
database_version	3.53.2

Xiaomi Miot

component_version	1.1.4
can_reach_server	ok
can_reach_spec	ok
logged_accounts	1
total_devices	5

Anything in the Supervisor logs that might be useful for us?

Anything in the app logs that might be useful for us?

00:00:00.718 [W] P-Netif-------: Successfully added an external route fc00::/7 in kernel
00:00:00.718 [W] P-Netif-------: Successfully added an external route fdbd:648b:9209:2:0:0::/96 in kernel

Additional information

Expected behavior: The OTBR add-on should not blindly claim the entire ULA space (fc00::/7), as it conflicts with standard home networks utilizing ULA for VLAN segmentation. It should either only route its specific Thread on-mesh prefix or provide a configuration toggle in the Add-on UI to disable the injection of the fc00::/7 route.

Workaround for affected users: Manually adding a more specific permanent static route using nmcli via the HA Advanced SSH terminal bypasses the OTBR trap: nmcli connection modify "Supervisor enp0s18" +ipv6.routes "fd30::/64 fe80::[router_gateway_mac]"

[tannerdsilva]

This is a huge issue for me. Looking forward to seeing this get fixed!

[tannerdsilva]

I've been able to burn some tokens on this issue and I've uncovered some interesting findings.

Obviously this is an issue either directly related to the upstream project, OR it is an issue with how that project is being used in this container.

In my initial testing, it's looking like the ladder is the case, and we might be able to correct this with a simple PR.

Will share more soon...

[tannerdsilva]

Update:

It looks like OTBR only opts to engage this fc00::/7 route when it is interacting with orphaned mesh partitions.

The unfortunate usage pattern of the current OTBR app is that the mesh gets a new "partition" (a unique address space of /64 size) every time the container is restarted. So OTBR is forced to use this "fallback route" a lot more than it probably should.

I am testing (and will PR) a modified version of OTBR that uses a static (and/or shared) OMR prefix across restarts. It eliminates all address churn and also eliminates OTBR's need to use the fc00::/7 route.

[tannerdsilva]

Hard to over-express how problematic this is. Such a deceptive thing, it's just a single fc00::7 route, how bad can this get?

It's bad. Really bad.

This basically creates an Ethernet loop....through the mesh, for anyone running more than two border routers.

Local traffic within the fc00::/7 range comes in through ethernet, then immediately goes back out the wireless thread interface. Eventually that traffic finds its way to another border router, making a loop.

I'm still working on developing my ideal solution to this - so far it looks like notable changes are required on the upstream projects, as well as a complete re-imagining of the firewall rules within the container itself. Working on all the above.

[tannerdsilva]

Solution is drafted.

Testing for a few more days before I submit my PR.

So far it's looking like a "route optimized" OTBR can greatly outperform the existing versions (it's a massive improvement), but from what I can tell, existing mesh structures will be unable to heal through this change and a complete recommissioning will be required to reap the benefits of the new routing. Quite unfortunate.

[tannerdsilva]

Sorry for the false alarm.

Today I discovered that meshes can be restored for continued use with my draft update.....thanks to the strategic use of "leadership priorities" in Thread.

[tannerdsilva]

#4803