XTLS/Xray-core · error

no available TUN interface name in range %s%d-%s%d

Error message

no available TUN interface name in range %s%d-%s%d

What it means

GetAvailableTunName scans utun10..utun1024 starting from a random offset and fails when every name in that range is already taken by an existing interface. It indicates interface-name exhaustion rather than a permission or syscall failure.

Source

Thrown at infra/conf/tun.go:91

	}

	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)

		if _, exists := usedNames[name]; !exists {
			return name, nil
		}
	}

	return "", fmt.Errorf(
		"no available TUN interface name in range %s%d-%s%d",
		tunNamePrefix,
		minTunIndex,
		tunNamePrefix,
		maxTunIndex,
	)
}

func randomInt(min, max int) (int, error) {
	value, err := rand.Int(
		rand.Reader,
		big.NewInt(int64(max-min+1)),
	)
	if err != nil {
		return 0, err
	}

	return min + int(value.Int64()), nil

View on GitHub (pinned to 7d214f8b09)

Solutions

1. List interfaces (`ifconfig -a` / `ip link`) and delete stale utun* devices or reboot to clear them
2. Kill orphaned processes still holding TUN fds (lsof | grep utun)
3. If legitimate usage needs >1015 interfaces, that exceeds the design range — reconsider the setup
4. After cleanup, retry starting xray

Example fix

# before: 1000+ leaked utuns
sudo ifconfig utun900 destroy   # macOS, repeat for leaked ids
# or simply reboot; then restart xray

// pre-flight: count free names before starting
ifaces, _ := net.Interfaces()
used := map[string]bool{}
for _, i := range ifaces { used[i.Name] = true }
free := 0
for n := 10; n <= 1024; n++ { if !used[fmt.Sprintf("utun%d", n)] { free++ } }
if free == 0 { return errors.New("utun range exhausted; clean stale interfaces") }

if _, err := conf.GetAvailableTunName(); err != nil {
    if strings.Contains(err.Error(), "no available TUN interface name") {
        // ops remediation: destroy leaked utuns or reboot
        log.Fatal("TUN names exhausted — remove leaked utun* interfaces and restart")
    }
    log.Fatal(err)
}

When it happens

Trigger: A system (typically macOS or a TUN-using platform with the utun naming convention) where 1015 interfaces named utun10..utun1024 all exist — usually leaked TUN handles from crashed VPN/proxy processes.

Common situations: Repeated crashes/restarts of xray or other VPN tools leaking utun devices; macOS systems with many stale utun interfaces from iCloud/VPN services plus leaked ones.

Related errors

• fail to get system interface information: %w
• fail to generate valid tun name: %w
• failed to determine if address is local:
• invalid source IP address:
• invalid destination IP address:

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