{"record":{"id":"9e8c36bb09b0ddd9","repo":"slackhq/nebula","slug":"failed-to-set-tun-mtu-v","errorCode":null,"errorMessage":"failed to set tun mtu: %v","messagePattern":"failed to set tun mtu: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"overlay/tun_darwin.go","lineNumber":182,"sourceCode":"func (t *tun) Activate() error {\n\tdevName := t.deviceBytes()\n\n\ts, err := unix.Socket(\n\t\tunix.AF_INET,\n\t\tunix.SOCK_DGRAM,\n\t\tunix.IPPROTO_IP,\n\t)\n\tif err != nil {\n\t\treturn err\n\t}\n\tdefer unix.Close(s)\n\n\tfd := uintptr(s)\n\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 {","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/tun_darwin.go#L164-L200","documentation":"During Activate on macOS, nebula opens a control socket for the device and sets the interface MTU with the SIOCSIFMTU ioctl using t.DefaultMTU. If that ioctl fails, the errno is wrapped in this error. It means the kernel refused to apply the MTU to the utun device.","triggerScenarios":"ioctl(fd, SIOCSIFMTU, ifreqMTU{devName, DefaultMTU}) fails during tun.Activate — device name wrong/nonexistent, permission denied (not root), or MTU value rejected by the kernel.","commonSituations":"Running nebula without root/sudo on macOS (ioctls on interfaces need privileges); tun.dev renamed/mismatched with the actual utun name; extremely small or large MTU values in config.","solutions":["Run nebula with root privileges (sudo) so SIOCSIFMTU is permitted.","Verify tun.dev matches the interface name reported at startup (e.g. utun5) and is not misconfigured.","Check tun.mtu in config; remove it to use the default (1300) if a custom value is rejected.","Confirm the utun interface still exists in `ifconfig` before Activate runs."],"exampleFix":"// before\nsudo ./nebula -config config.yml   # run as non-root user fails SIOCSIFMTU\n// after\nsudo ./nebula -config config.yml   # run as root, or setcap/grant network privileges","handlingStrategy":"validation","validationCode":"if os.Geteuid() != 0 {\n    return errors.New(\"nebula needs root on macOS to set interface MTU\")\n}","typeGuard":null,"tryCatchPattern":"if err := start(); err != nil && strings.Contains(err.Error(), \"failed to set tun mtu\") {\n    // advise: run with sudo, check tun.dev and tun.mtu config\n}","preventionTips":["Always run nebula as root (sudo) on macOS","Keep tun.mtu within sane bounds (e.g. 1300) or omit it","Verify tun.dev matches the interface nebula actually created"],"tags":["macos","darwin","mtu","ioctl","permissions"],"backgroundTag":"ioctl-mtu-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"}