{"record":{"id":"8d100bd9cde6e827","repo":"slackhq/nebula","slug":"system-socket-v","errorCode":null,"errorMessage":"system socket: %v","messagePattern":"system socket: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"overlay/tun_darwin.go","lineNumber":94,"sourceCode":"\tLifetime   addrLifetime\n}\n\nfunc newTun(c *config.C, l *slog.Logger, vpnNetworks []netip.Prefix, _ bool) (*tun, error) {\n\tname := c.GetString(\"tun.dev\", \"\")\n\tifIndex := -1\n\tif name != \"\" && name != \"utun\" {\n\t\t_, err := fmt.Sscanf(name, \"utun%d\", &ifIndex)\n\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","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/tun_darwin.go#L76-L112","documentation":"newTun on macOS creates a utun control socket via unix.Socket(AF_SYSTEM, SOCK_DGRAM, AF_SYS_CONTROL). If that syscall fails, the raw errno is wrapped in this error. It indicates the kernel refused to open the special system-domain datagram socket used to talk to the utun kernel control interface.","triggerScenarios":"unix.Socket(AF_SYSTEM, SOCK_DGRAM, AF_SYS_CONTROL) returns an error at startup of newTun on Darwin — e.g. sandboxed/seatbelt profiles denying AF_SYSTEM sockets, heavily restricted CI macOS runners, or syscall emulation layers.","commonSituations":"Running nebula inside a macOS app sandbox without the com.apple.network.extension entitlements; running under jail/enterprise MDM restrictions; trying to create a second utun after resource limits.","solutions":["Run nebula unsandboxed (outside App Sandbox) or grant the process the network extension entitlement that allows AF_SYSTEM socket creation.","Check MDM/security profiles that block AF_SYSTEM sockets for the user.","Ensure macOS kernel integrity protections allow third-party utun devices (up to 256 utun interfaces).","Retry after rebooting if the kernel socket table is exhausted."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := run(); err != nil && strings.Contains(err.Error(), \"system socket:\") {\n    // check sandbox/entitlements; prompt user to run outside App Sandbox\n    log.Fatalf(\"cannot open utun control socket: %v\", err)\n}","preventionTips":["Do not run nebula inside the macOS App Sandbox without network extension entitlements","Test TUN creation on the exact macOS runner/device used in production","Keep nebula running unsandboxed or wrapped in a NetworkExtension"],"tags":["macos","darwin","utun","socket","syscall"],"backgroundTag":"utun-socket-creation-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"}