XTLS/Xray-core · error

failed to add interface address {address}

Error message

failed to add interface address {address}

What it means

After parsing a gateway address successfully, netlink.AddrAdd assigns it to the TUN link. If the kernel rejects the operation the already-added addresses are rolled back and this error wraps the netlink failure. Typical base causes: EEXIST (address already on the interface), ENODEV (link gone), or EPERM (missing CAP_NET_ADMIN).

Source

Thrown at proxy/tun/tun_linux.go:247

}

func setinterface(network, address string, fd uintptr, iface *net.Interface) error {
	return unix.BindToDevice(int(fd), iface.Name)
}

func (t *LinuxTun) setInterfaceAddresses() error {
	if len(t.options.Gateway) == 0 {
		return nil
	}
	for _, address := range t.options.Gateway {
		addr, err := netlink.ParseAddr(address)
		if err != nil {
			_ = t.unsetInterfaceAddresses()
			return errors.New("invalid interface address ", address).Base(err)
		}
		if err := netlink.AddrAdd(t.tunLink, addr); err != nil {
			_ = t.unsetInterfaceAddresses()
			return errors.New("failed to add interface address ", address).Base(err)
		}
		t.interfaceAddresses = append(t.interfaceAddresses, *addr)
	}
	return nil
}

func (t *LinuxTun) unsetInterfaceAddresses() error {
	var errs []error
	for i := len(t.interfaceAddresses) - 1; i >= 0; i-- {
		address := t.interfaceAddresses[i]
		if err := netlink.AddrDel(t.tunLink, &address); err != nil {
			errs = append(errs, errors.New("failed to delete interface address ", address.String()).Base(err))
		}
	}
	t.interfaceAddresses = nil
	return errors.Combine(errs...)
}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Run Xray as root or grant CAP_NET_ADMIN (e.g. docker --cap-add=NET_ADMIN)
2. Check `ip addr show <tun>` and remove stale addresses, or dedupe the gateway list
3. Ensure the TUN device still exists at assignment time (no concurrent teardown)

Example fix

# before: stale address present
ip addr show tun0  # 172.19.0.1/30 already assigned

# after
ip addr flush dev tun0
# then start xray

// pre-flight: ensure privileges and no conflicting addresses
if os.Geteuid() != 0 {
	log.Fatal("tun mode requires root or CAP_NET_ADMIN")
}
// dedupe gateways
seen := map[string]bool{}
for _, gw := range cfg.Gateway {
	if seen[gw] { log.Fatalf("duplicate gateway %q", gw) }
	seen[gw] = true
}

if err := tun.Start(); err != nil {
	if strings.Contains(err.Error(), "failed to add interface address") {
		// check `ip addr show <tun>`, flush stale addresses, restart
	}
}

When it happens

Trigger: Running without root/CAP_NET_ADMIN; a TUN interface that already carries the same address (e.g. from a previous unclean shutdown or an external script); the link being deleted concurrently; duplicate entries in the gateway list.

Common situations: Xray started as non-root; a network-manager or previous Xray run left addresses on the device; duplicate gateway values in config; container without NET_ADMIN capability.

Related errors

• invalid interface address {address}
• failed to delete interface address {address}
• failed to add system route {cidr}
• failed to delete system route
• unable to set ips

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/1a902586ad52ed11. Report an issue: GitHub.