XTLS/Xray-core · error

fail to get system interface information: %w

Error message

fail to get system interface information: %w

What it means

GetAvailableTunName enumerates system network interfaces with net.Interfaces() to find a free utun name; failure at the syscall/OS level is wrapped here. It means the process could not even list interfaces, before any name allocation is attempted.

Source

Thrown at infra/conf/tun.go:67

	if config.Desc == "" {
		config.Desc = "Wintun"
	}
	if config.MTU == 0 {
		config.MTU = 1500
	}
	return config, nil
}

const (
	tunNamePrefix = "utun"
	minTunIndex   = 10
	maxTunIndex   = 1024
)

func GetAvailableTunName() (string, error) {
	interfaces, err := net.Interfaces()
	if err != nil {
		return "", fmt.Errorf("fail to get system interface information: %w", err)
	}

	usedNames := make(map[string]struct{}, len(interfaces))
	for _, iface := range interfaces {
		usedNames[iface.Name] = struct{}{}
	}

	startIndex, err := randomInt(minTunIndex, maxTunIndex)
	if err != nil {
		return "", fmt.Errorf("fail to generate valid tun name: %w", err)
	}

	rangeSize := maxTunIndex - minTunIndex + 1

	for offset := 0; offset < rangeSize; offset++ {
		index := minTunIndex + (startIndex-minTunIndex+offset)%rangeSize
		name := tunNamePrefix + strconv.Itoa(index)

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Check the wrapped err for the OS-level cause
2. In containers: run with host network namespace or ensure /sys and netlink are available; add NET_ADMIN capability if creating TUN
3. On hosts: verify `ip link` or `ifconfig` works as the same user
4. If TUN is not needed, remove the tun inbound from the config

Example fix

# before: docker run --security-opt seccomp=strict ...
# after: allow interface enumeration and TUN creation
docker run --cap-add NET_ADMIN --sysfs /sys ... xray

// pre-flight: confirm interface enumeration works in this environment
if _, err := net.Interfaces(); err != nil {
    return fmt.Errorf("environment cannot enumerate interfaces; TUN inbound unsupported here: %w", err)
}

name, err := conf.GetAvailableTunName()
if err != nil {
    if strings.Contains(err.Error(), "fail to get system interface information") {
        // environment problem, not name exhaustion: surface ops action
        log.Fatal("cannot enumerate network interfaces — check container caps / /sys mounts: ", err)
    }
    log.Fatal(err)
}

When it happens

Trigger: Running with tun inbound enabled on a system where interface enumeration fails: restricted containers/sandboxes without netlink or sysctl access, broken /proc or /sys mounts, or unusual capability drops.

Common situations: Docker with an overly restrictive seccomp/capabilities profile; minimal rootfs containers (no /sys/class/net); chroot environments; macOS sandbox-exec profiles denying network syscalls.

Related errors

• failed to add interface address {address}
• failed to add system route {cidr}
• unable to set routes
• unable to set ips
• fail to generate valid tun name: %w

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