{"record":{"id":"bc926199a1adf48e","repo":"slackhq/nebula","slug":"failed-to-set-tun-v4-address-s","errorCode":null,"errorMessage":"failed to set tun v4 address: %s","messagePattern":"failed to set tun v4 address: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"overlay/tun_darwin.go","lineNumber":255,"sourceCode":"\t\tAddr: unix.RawSockaddrInet4{\n\t\t\tLen:    unix.SizeofSockaddrInet4,\n\t\t\tFamily: unix.AF_INET,\n\t\t\tAddr:   network.Addr().As4(),\n\t\t},\n\t\tDstAddr: unix.RawSockaddrInet4{\n\t\t\tLen:    unix.SizeofSockaddrInet4,\n\t\t\tFamily: unix.AF_INET,\n\t\t\tAddr:   network.Addr().As4(),\n\t\t},\n\t\tMaskAddr: unix.RawSockaddrInet4{\n\t\t\tLen:    unix.SizeofSockaddrInet4,\n\t\t\tFamily: unix.AF_INET,\n\t\t\tAddr:   prefixToMask(network).As4(),\n\t\t},\n\t}\n\n\tif err := ioctl(uintptr(s), unix.SIOCAIFADDR, uintptr(unsafe.Pointer(&ifr))); err != nil {\n\t\treturn fmt.Errorf(\"failed to set tun v4 address: %s\", err)\n\t}\n\n\terr = addRoute(network, t.linkAddr)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\treturn nil\n}\n\nfunc (t *tun) activate6(network netip.Prefix) error {\n\ts, err := unix.Socket(\n\t\tunix.AF_INET6,\n\t\tunix.SOCK_DGRAM,\n\t\tunix.IPPROTO_IP,\n\t)\n\tif err != nil {\n\t\treturn err","sourceCodeStart":237,"sourceCodeEnd":273,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/tun_darwin.go#L237-L273","documentation":"activate4() assigns the IPv4 address and netmask to the utun device using the SIOCAIFADDR ioctl on an AF_INET control socket. This error wraps the errno when the kernel rejects the address assignment for one of the configured VPN networks. The address being set comes from tun routes in the nebula config, so a bad network specification commonly surfaces here.","triggerScenarios":"Activate() -> activate4() for each IPv4 vpnNetwork prefix; SIOCAIFADDR fails, e.g. the configured address is already assigned to another interface on the host, or the address/mask is invalid for the interface.","commonSituations":"The chosen tun IP (e.g. 10.x.x.x) collides with an existing host interface; another VPN client already holds the address; running two nebula instances with overlapping tun ranges; EPERM when lacking privileges.","solutions":["Check the wrapped errno (EEXIST => address already in use) and pick a non-conflicting tun IP range in the config.","Run nebula with sufficient privileges (root or CAP_NET_ADMIN equivalent) so SIOCAIFADDR is permitted.","Stop the other VPN or instance currently holding the address, then retry.","Validate the tun address/mask in the config is a well-formed IPv4 prefix."],"exampleFix":"// before: address collides with the host LAN\ntun:\n  routes:\n    - route: 192.168.1.0/24\n// after: use a dedicated range for the overlay\ntun:\n  routes:\n    - route: 10.100.0.0/16","handlingStrategy":"validation","validationCode":"ip, err := netip.ParsePrefix(cfg.TunRoute)\nif err != nil || !ip.Addr().Is4() {\n    return fmt.Errorf(\"tun route must be a valid IPv4 prefix: %w\", err)\n}\n// also confirm no other host interface already holds this address\nout, _ := exec.Command(\"ifconfig\", \"-a\").Output()\nif strings.Contains(string(out), ip.Addr().String()) {\n    return fmt.Errorf(\"address %s already assigned on host\", ip.Addr())\n}","typeGuard":null,"tryCatchPattern":"if err := iface.Activate(); err != nil {\n    if strings.Contains(err.Error(), \"failed to set tun v4 address\") {\n        // EEXIST: pick a non-conflicting overlay range and retry\n    }\n    return err\n}","preventionTips":["Use a dedicated overlay range (e.g. 10.x/16) that doesn't overlap host LANs","Run with root/admin privileges","Stop other VPN clients before starting nebula","Validate IPv4 prefixes in the config before launch"],"tags":["network","darwin","ipv4","ioctl","address-assignment"],"backgroundTag":"tun-address-assignment-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"}