{"record":{"id":"62a95ab8d6fddd0e","repo":"slackhq/nebula","slug":"failed-to-initialize-interface-s","errorCode":null,"errorMessage":"failed to initialize interface: %s","messagePattern":"failed to initialize interface: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"main.go","lineNumber":303,"sourceCode":"\t\treQueryWait:           c.GetDuration(\"timers.requery_wait_duration\", defaultReQueryWait),\n\t\tDropLocalBroadcast:    c.GetBool(\"tun.drop_local_broadcast\", false),\n\t\tDropMulticast:         c.GetBool(\"tun.drop_multicast\", false),\n\t\troutines:              routines,\n\t\tMessageMetrics:        messageMetrics,\n\t\tversion:               buildVersion,\n\t\trelayManager:          NewRelayManager(ctx, l, hostMap, c),\n\t\tpunchy:                punchy,\n\t\tConntrackCacheTimeout: conntrackCacheTimeout,\n\t\tCpuAffinity:           cpuAffinity,\n\t\tPinThreads:            pinThreads,\n\t\tl:                     l,\n\t}\n\n\tvar ifce *Interface\n\tif !configTest {\n\t\tifce, err = NewInterface(ctx, ifConfig)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to initialize interface: %s\", err)\n\t\t}\n\n\t\tifce.writers = udpConns\n\t\tlightHouse.ifce = ifce\n\n\t\tifce.RegisterConfigChangeCallbacks(c)\n\t\tifce.reloadDisconnectInvalid(c)\n\t\tifce.reloadSendRecvError(c)\n\t\tifce.reloadAcceptRecvError(c)\n\n\t\thandshakeManager.f = ifce\n\t\tgo handshakeManager.Run(ctx)\n\n\t\tpunchy.Start(ctx, ifce, hostMap, lightHouse)\n\t}\n\n\tstats, err := newStatsServerFromConfig(ctx, l, c, buildVersion, configTest)\n\tif err != nil {","sourceCodeStart":285,"sourceCodeEnd":321,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/main.go#L285-L321","documentation":"Wraps the error from NewInterface when the nebula Interface could not be initialized during main startup (only when configTest is false). The underlying error (in %s) explains the real cause — commonly TUN device creation failure, invalid routines/MTU config, or cipher/route setup problems.","triggerScenarios":"Main startup calls NewInterface(ctx, ifConfig); any error inside (tun device open failure, bad MTU, invalid config for the interface) is wrapped with this message.","commonSituations":"Running without CAP_NET_ADMIN/root so /dev/net/tun can't be opened; missing tun module in containers; MTU or routines misconfiguration; another process holding the tun device.","solutions":["Run with root/CAP_NET_ADMIN or inside a container with --device /dev/net/tun and privileged networking","Check the wrapped inner error (%s) for the actual cause and fix that specifically","Verify tun/MTU/routines settings in config.yml","Ensure no stale nebula process still holds the tun device"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// preflight: can we open/create a tun device?\nf, err := tun.NewDevice(...)\nif err != nil {\n    log.Fatalf(\"cannot create tun device (need root/CAP_NET_ADMIN or /dev/net/tun): %v\", err)\n}","typeGuard":null,"tryCatchPattern":"ifce, err := NewInterface(ctx, ifConfig)\nif err != nil {\n    logger.Error(fmt.Sprintf(\"failed to initialize interface: %s\", err))\n    return nil, fmt.Errorf(\"failed to initialize interface: %s\", err)\n}","preventionTips":["Run nebula with root or CAP_NET_ADMIN and ensure /dev/net/tun exists","In containers, pass --device /dev/net/tun and NET_ADMIN capability","Sanity-check MTU and routines config before deploy","Use 'nebula -test' plus an explicit tun device check in startup scripts"],"tags":["startup","tun-device","interface"],"backgroundTag":"tun-device-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"}