XTLS/Xray-core · error

invalid interface address {address}

Error message

invalid interface address {address}

What it means

While assigning gateway addresses to the TUN interface, Xray calls netlink.ParseAddr on each entry of the tun inbound's "gateway" setting. If the string is not a valid network address (optionally with /prefix), parsing fails, already-applied addresses are rolled back, and this wrapped error is returned.

Source

Thrown at proxy/tun/tun_linux.go:243

		FDs:               []int{t.tunFd},
		MTU:               t.options.MTU,
		RXChecksumOffload: true,
	})
}

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))
		}
	}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Correct the gateway entry to a valid address or address/prefix, e.g. "172.19.0.1/30"
2. Use prefix-length notation (/30), never dotted netmask notation
3. Validate every gateway string with a parse before starting Xray (see validationCode)

Example fix

// before
"gateway": ["172.19.0.1 255.255.255.252"]

// after
"gateway": ["172.19.0.1/30"]

for _, gw := range cfg.Gateway {
	if _, err := netlink.ParseAddr(gw); err != nil {
		log.Fatalf("bad gateway %q: %v", gw, err)
	}
}

When it happens

Trigger: A gateway entry like "172.19.0.1" is valid, but entries such as "172.19.0.1/33", "fe80::1/129", "not-an-ip", an empty string, or trailing whitespace/garbage characters fail ParseAddr.

Common situations: Hand-edited JSON with typos; copying a subnet mask notation like "255.255.255.252" instead of prefix length; YAML env-substitution leaving an empty value.

Related errors

• failed to add interface address {address}
• failed to delete interface address {address}
• invalid xray.tun.fd: file descriptor is not a TUN device
• invalid xray.tun.fd: TUN device must use IFF_NO_PI
• invalid xray.tun.fd: TUN device name {actualName} does not m

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