{"record":{"id":"22790075a9cadbdb","repo":"slackhq/nebula","slug":"ctliocginfo-v","errorCode":null,"errorMessage":"CTLIOCGINFO: %v","messagePattern":"CTLIOCGINFO: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"overlay/tun_darwin.go","lineNumber":102,"sourceCode":"\t\tif err != nil || ifIndex < 0 {\n\t\t\t// NOTE: we don't make this error so we don't break existing\n\t\t\t// configs that set a name before it was used.\n\t\t\tl.Warn(\"interface name must be utun[0-9]+ on Darwin, ignoring\")\n\t\t\tifIndex = -1\n\t\t}\n\t}\n\n\tfd, err := unix.Socket(unix.AF_SYSTEM, unix.SOCK_DGRAM, unix.AF_SYS_CONTROL)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"system socket: %v\", err)\n\t}\n\n\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)","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/tun_darwin.go#L84-L120","documentation":"After opening the AF_SYSTEM socket, newTun issues the CTLIOCGINFO ioctl to resolve the utun kernel control ID from the control name (com.apple.net.utun_control). If that ioctl fails, this error wraps the errno. Without the control ID the subsequent connect cannot identify the kernel control.","triggerScenarios":"unix.IoctlCtlInfo(fd, ctlInfo) returns an error because the utun control name is not registered with the kernel, the fd is invalid, or the process lacks permission to issue ioctls on the system socket.","commonSituations":"Running in restricted environments (containers on macOS hosts, virtualized CI runners) where the utun kernel control is unavailable; corrupted or non-Darwin kernel; running as a user blocked from kernel controls.","solutions":["Run nebula directly on macOS (not inside a container/VM without utun support).","Verify the binary is built for darwin (GOOS=darwin); a mismatched build cannot access macOS kernel controls.","Re-run with elevated permissions to rule out permission-based ioctl failures.","Reboot the host if the network kernel extensions are in a bad state."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := start(); err != nil && strings.Contains(err.Error(), \"CTLIOCGINFO\") {\n    // transient kernel state: bounded retry with backoff, then escalate\n    time.Sleep(500 * time.Millisecond)\n    return start()\n}","preventionTips":["Run on real macOS (not containers/VMs lacking utun support)","Build with GOOS=darwin for macOS deployments","Bounded-retry TUN startup to absorb transient kernel-control failures"],"tags":["macos","darwin","utun","ioctl","kernel"],"backgroundTag":"utun-control-ioctl-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"}