{"record":{"id":"29ff65b16c259a6b","repo":"XTLS/Xray-core","slug":"fail-to-generate-valid-tun-name-w","errorCode":null,"errorMessage":"fail to generate valid tun name: %w","messagePattern":"fail to generate valid tun name: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"infra/conf/tun.go","lineNumber":77,"sourceCode":"\ttunNamePrefix = \"utun\"\n\tminTunIndex   = 10\n\tmaxTunIndex   = 1024\n)\n\nfunc GetAvailableTunName() (string, error) {\n\tinterfaces, err := net.Interfaces()\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"fail to get system interface information: %w\", err)\n\t}\n\n\tusedNames := make(map[string]struct{}, len(interfaces))\n\tfor _, iface := range interfaces {\n\t\tusedNames[iface.Name] = struct{}{}\n\t}\n\n\tstartIndex, err := randomInt(minTunIndex, maxTunIndex)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"fail to generate valid tun name: %w\", err)\n\t}\n\n\trangeSize := maxTunIndex - minTunIndex + 1\n\n\tfor offset := 0; offset < rangeSize; offset++ {\n\t\tindex := minTunIndex + (startIndex-minTunIndex+offset)%rangeSize\n\t\tname := tunNamePrefix + strconv.Itoa(index)\n\n\t\tif _, exists := usedNames[name]; !exists {\n\t\t\treturn name, nil\n\t\t}\n\t}\n\n\treturn \"\", fmt.Errorf(\n\t\t\"no available TUN interface name in range %s%d-%s%d\",\n\t\ttunNamePrefix,\n\t\tminTunIndex,\n\t\ttunNamePrefix,","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/infra/conf/tun.go#L59-L95","documentation":"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.","triggerScenarios":"crypto/rand.Reader returns an error — typically on systems with a broken/getting-ready entropy source, or in early boot / heavily constrained VMs.","commonSituations":"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.","solutions":["Check the wrapped error for the OS cause","Ensure /dev/urandom (or getrandom) is available in the environment (device nodes in containers/chroots)","Wait for entropy readiness (check /proc/sys/kernel/random/entropy_avail) and retry","As a workaround, specify an explicit tun name in config if supported, avoiding the random pick"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"var name string\nerr := retry(3, func() error {\n    var e error\n    name, e = conf.GetAvailableTunName()\n    if e != nil && strings.Contains(e.Error(), \"fail to generate valid tun name\") {\n        return e // transient entropy-read failure, worth retrying\n    }\n    return e\n})","preventionTips":["Ensure /dev/urandom exists in chroots/containers","Check entropy availability on minimal VMs at boot","Treat persistent failure as an environment defect, not a config one"],"tags":["tun","crypto-rand","entropy","os"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}