XTLS/Xray-core · error

fail to generate valid tun name: %w

Error message

fail to generate valid tun name: %w

What it means

GetAvailableTunName picks a random start index via randomInt(minTunIndex, maxTunIndex), which reads from crypto/rand.Reader; this error wraps a failure of that read. It is a defensive path around OS entropy-source failure, not a config problem.

Source

Thrown at infra/conf/tun.go:77

	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)

		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,

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Check the wrapped error for the OS cause
2. Ensure /dev/urandom (or getrandom) is available in the environment (device nodes in containers/chroots)
3. Wait for entropy readiness (check /proc/sys/kernel/random/entropy_avail) and retry
4. As a workaround, specify an explicit tun name in config if supported, avoiding the random pick

var name string
err := retry(3, func() error {
    var e error
    name, e = conf.GetAvailableTunName()
    if e != nil && strings.Contains(e.Error(), "fail to generate valid tun name") {
        return e // transient entropy-read failure, worth retrying
    }
    return e
})

When it happens

Trigger: crypto/rand.Reader returns an error — typically on systems with a broken/getting-ready entropy source, or in early boot / heavily constrained VMs.

Common situations: Freshly booted minimal VMs; chroots without /dev/urandom; kernel entropy starvation on old hosts; extremely rare on modern Linux where getrandom(2) blocks instead of erroring.

Related errors

• failed to create client
• fail to get system interface information: %w
• no available TUN interface name in range %s%d-%s%d
• unexpected query strategy
• Unable to parse CIDR for Fake DNS IP assignment

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