{"record":{"id":"2b09069deda42986","repo":"slackhq/nebula","slug":"unable-to-discover-link-addr-for-tun-interface","errorCode":null,"errorMessage":"unable to discover link_addr for tun interface","messagePattern":"unable to discover link_addr for tun interface","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"overlay/tun_darwin.go","lineNumber":196,"sourceCode":"\n\t// Set the MTU on the device\n\tifm := ifreqMTU{Name: devName, MTU: int32(t.DefaultMTU)}\n\tif err = ioctl(fd, unix.SIOCSIFMTU, uintptr(unsafe.Pointer(&ifm))); err != nil {\n\t\treturn fmt.Errorf(\"failed to set tun mtu: %v\", err)\n\t}\n\n\t// Get the device flags\n\tifrf := ifReq{Name: devName}\n\tif err = ioctl(fd, unix.SIOCGIFFLAGS, uintptr(unsafe.Pointer(&ifrf))); err != nil {\n\t\treturn fmt.Errorf(\"failed to get tun flags: %s\", err)\n\t}\n\n\tlinkAddr, err := getLinkAddr(t.Device)\n\tif err != nil {\n\t\treturn err\n\t}\n\tif linkAddr == nil {\n\t\treturn fmt.Errorf(\"unable to discover link_addr for tun interface\")\n\t}\n\tt.linkAddr = linkAddr\n\n\tfor _, network := range t.vpnNetworks {\n\t\tif network.Addr().Is4() {\n\t\t\terr = t.activate4(network)\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t} else {\n\t\t\terr = t.activate6(network)\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t}\n\t}\n\n\t// Run the interface","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/tun_darwin.go#L178-L214","documentation":"Activate calls getLinkAddr to find the link-layer (AF_LINK) address record for the utun interface, which nebula needs for route/address setup. If the lookup succeeds but returns no matching link address, this error is returned. It means the kernel knows the interface by name but no link_addr entry could be discovered for it.","triggerScenarios":"getLinkAddr(t.Device) returns (nil, nil) during tun.Activate — the utun interface exists but has no AF_LINK sockaddr entry, e.g. the interface was just created and is not fully registered, or the name lookup matched nothing enumerable.","commonSituations":"Interface torn down between creation and Activate; macOS kernel state where the utun lacks a link-layer address; dev name mismatch so enumeration finds no matching interface.","solutions":["Restart nebula so the utun is recreated and its link address registered before Activate.","Verify tun.dev matches the actual interface name from the utun connect step.","Update macOS if the kernel intermittently omits AF_LINK entries for fresh utun devices.","Stop competing VPN software that may be manipulating the interface table concurrently."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := start(); err != nil && strings.Contains(err.Error(), \"unable to discover link_addr\") {\n    // interface registered without link addr: retry startup once\n}","preventionTips":["Restart nebula if the utun was created but not fully registered","Keep tun.dev consistent with the name reported at startup","Update macOS if link_addr discovery intermittently fails on fresh utun devices"],"tags":["macos","darwin","utun","link-address","interface"],"backgroundTag":"link-address-not-found","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"}