{"record":{"id":"774dd44d1696134c","repo":"slackhq/nebula","slug":"failed-to-retrieve-tun-name-w","errorCode":null,"errorMessage":"failed to retrieve tun name: %w","messagePattern":"failed to retrieve tun name: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"overlay/tun_darwin.go","lineNumber":115,"sourceCode":"\tvar ctlInfo = &unix.CtlInfo{}\n\tcopy(ctlInfo.Name[:], utunControlName)\n\n\terr = unix.IoctlCtlInfo(fd, ctlInfo)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"CTLIOCGINFO: %v\", err)\n\t}\n\n\terr = unix.Connect(fd, &unix.SockaddrCtl{\n\t\tID:   ctlInfo.Id,\n\t\tUnit: uint32(ifIndex) + 1,\n\t})\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"SYS_CONNECT: %v\", err)\n\t}\n\n\tname, err = unix.GetsockoptString(fd, unix.AF_SYS_CONTROL, _UTUN_OPT_IFNAME)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to retrieve tun name: %w\", err)\n\t}\n\n\terr = unix.SetNonblock(fd, true)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"SetNonblock: %v\", err)\n\t}\n\n\tt := &tun{\n\t\tf:           os.NewFile(uintptr(fd), \"\"),\n\t\tDevice:      name,\n\t\tvpnNetworks: vpnNetworks,\n\t\tDefaultMTU:  c.GetInt(\"tun.mtu\", DefaultMTU),\n\t\tl:           l,\n\t}\n\n\terr = t.reload(c, true)\n\tif err != nil {\n\t\treturn nil, err","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/tun_darwin.go#L97-L133","documentation":"After connecting to the utun control, newTun queries the assigned interface name with getsockopt(AF_SYS_CONTROL, _UTUN_OPT_IFNAME). If the kernel cannot report the interface name for this socket, this error wraps the errno. It means the utun connection exists but the kernel did not associate an interface name with it.","triggerScenarios":"unix.GetsockoptString(fd, AF_SYS_CONTROL, _UTUN_OPT_IFNAME) returns an error right after a successful Connect — typically when the utun attach was torn down concurrently or the kernel state is inconsistent.","commonSituations":"Race with another VPN service destroying the utun just created; running on unusual/older macOS versions where the utun option behaves differently; heavily loaded hosts where the interface registration lagged.","solutions":["Retry starting nebula — this is often transient kernel-state related.","Let macOS auto-select the unit (omit tun.dev) to reduce attach/teardown races with other VPNs.","Stop competing VPN clients (Cisco AnyConnect, iCloud Private Relay, etc.) that churn utun interfaces.","Update macOS; very old kernel versions may not support the ifname option reliably."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := start(); err != nil && strings.Contains(err.Error(), \"failed to retrieve tun name\") {\n    // usually transient: retry with backoff before surfacing to the user\n}","preventionTips":["Avoid starting/stopping multiple VPN clients concurrently on macOS","Use auto-assigned utun units to minimize attach/teardown races","Keep macOS updated; add bounded retries around TUN startup"],"tags":["macos","darwin","utun","getsockopt","race-condition"],"backgroundTag":"utun-ifname-retrieval-failed","analyzedSha":"dd8f660c0ac37903ec4080ca4d3c861ba9342ceb","analyzedAt":"2026-09-03T11:13:55.444Z","contentChangedAt":"2026-09-03T11:13:55.444Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}