{"record":{"id":"3a7c2a60beee5d51","repo":"slackhq/nebula","slug":"failed-to-run-tun-device-s-3a7c2a","errorCode":null,"errorMessage":"failed to run tun device: %s","messagePattern":"failed to run tun device: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"overlay/tun_linux.go","lineNumber":508,"sourceCode":"\t\treturn fmt.Errorf(\"failed to bring the tun device up: %s\", err)\n\t}\n\n\t//set route MTU\n\tfor i := range t.vpnNetworks {\n\t\tif err = t.setDefaultRoute(t.vpnNetworks[i]); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to set default route MTU: %w\", err)\n\t\t}\n\t}\n\n\t// Set the routes\n\tif err = t.addRoutes(false); err != nil {\n\t\treturn err\n\t}\n\n\t// Run the interface\n\tifrf.Flags = ifrf.Flags | unix.IFF_UP | unix.IFF_RUNNING\n\tif err = ioctl(t.ioctlFd, unix.SIOCSIFFLAGS, uintptr(unsafe.Pointer(&ifrf))); err != nil {\n\t\treturn fmt.Errorf(\"failed to run tun device: %s\", err)\n\t}\n\n\treturn nil\n}\n\nfunc (t *tun) setMTU() {\n\t// Set the MTU on the device\n\tifm := ifreqMTU{Name: t.deviceBytes(), MTU: int32(t.MaxMTU)}\n\tif err := ioctl(t.ioctlFd, unix.SIOCSIFMTU, uintptr(unsafe.Pointer(&ifm))); err != nil {\n\t\t// This is currently a non fatal condition because the route table must have the MTU set appropriately as well\n\t\tt.l.Error(\"Failed to set tun mtu\", \"error\", err)\n\t}\n}\n\nfunc (t *tun) setDefaultRoute(cidr netip.Prefix) error {\n\tdr := &net.IPNet{\n\t\tIP:   cidr.Masked().Addr().AsSlice(),\n\t\tMask: net.CIDRMask(cidr.Bits(), cidr.Addr().BitLen()),","sourceCodeStart":490,"sourceCodeEnd":526,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/tun_linux.go#L490-L526","documentation":"Raised in tun.Activate as the final step: the SIOCSIFFLAGS ioctl that sets IFF_UP|IFF_RUNNING on the tun interface fails. All prior setup (name, link, addresses, routes) succeeded, but the kernel refused to mark the device running.","triggerScenarios":"Activate() calls ioctl(t.ioctlFd, SIOCSIFFLAGS, ...) with Flags|IFF_UP|IFF_RUNNING and the kernel returns an error — permissions or the device disappeared late in setup.","commonSituations":"Missing CAP_NET_ADMIN; concurrent teardown by network management daemons; exotic kernels/seccomp profiles blocking SIOCSIFFLAGS.","solutions":["Run with root/CAP_NET_ADMIN so IFF_RUNNING can be set.","Check %s errno: EPERM = privileges, ENODEV = device removed mid-activation.","Ensure no external daemon deletes or reconfigures the tun during startup.","Retry activation if transient."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// privileges + device presence checked just before the final flags set\nif os.Geteuid() != 0 && !hasCapNetAdmin() {\n    return errors.New(\"setting IFF_UP|IFF_RUNNING requires CAP_NET_ADMIN\")\n}\nif _, err := netlink.LinkByName(devName); err != nil {\n    return fmt.Errorf(\"device %s vanished during activate\", devName)\n}","typeGuard":null,"tryCatchPattern":"if err := t.Activate(netstack); err != nil {\n    if strings.Contains(err.Error(), \"failed to run tun device\") {\n        log.Error(\"could not set IFF_RUNNING; check privileges/device\", \"cause\", err)\n    }\n}","preventionTips":["Run with root/CAP_NET_ADMIN","Confirm no concurrent teardown of the tun during activation","Check seccomp/apparmor profiles don't block SIOCSIFFLAGS"],"tags":["network","tun","linux","ioctl"],"backgroundTag":"operation-not-permitted","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"}