slackhq/nebula · critical

failed to initialize interface: %s

Error message

failed to initialize interface: %s

What it means

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.

Source

Thrown at main.go:303

		reQueryWait:           c.GetDuration("timers.requery_wait_duration", defaultReQueryWait),
		DropLocalBroadcast:    c.GetBool("tun.drop_local_broadcast", false),
		DropMulticast:         c.GetBool("tun.drop_multicast", false),
		routines:              routines,
		MessageMetrics:        messageMetrics,
		version:               buildVersion,
		relayManager:          NewRelayManager(ctx, l, hostMap, c),
		punchy:                punchy,
		ConntrackCacheTimeout: conntrackCacheTimeout,
		CpuAffinity:           cpuAffinity,
		PinThreads:            pinThreads,
		l:                     l,
	}

	var ifce *Interface
	if !configTest {
		ifce, err = NewInterface(ctx, ifConfig)
		if err != nil {
			return nil, fmt.Errorf("failed to initialize interface: %s", err)
		}

		ifce.writers = udpConns
		lightHouse.ifce = ifce

		ifce.RegisterConfigChangeCallbacks(c)
		ifce.reloadDisconnectInvalid(c)
		ifce.reloadSendRecvError(c)
		ifce.reloadAcceptRecvError(c)

		handshakeManager.f = ifce
		go handshakeManager.Run(ctx)

		punchy.Start(ctx, ifce, hostMap, lightHouse)
	}

	stats, err := newStatsServerFromConfig(ctx, l, c, buildVersion, configTest)
	if err != nil {

View on GitHub (pinned to dd8f660c0a)

Solutions

1. Run with root/CAP_NET_ADMIN or inside a container with --device /dev/net/tun and privileged networking
2. Check the wrapped inner error (%s) for the actual cause and fix that specifically
3. Verify tun/MTU/routines settings in config.yml
4. Ensure no stale nebula process still holds the tun device

// preflight: can we open/create a tun device?
f, err := tun.NewDevice(...)
if err != nil {
    log.Fatalf("cannot create tun device (need root/CAP_NET_ADMIN or /dev/net/tun): %v", err)
}

ifce, err := NewInterface(ctx, ifConfig)
if err != nil {
    logger.Error(fmt.Sprintf("failed to initialize interface: %s", err))
    return nil, fmt.Errorf("failed to initialize interface: %s", err)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• no outside connection
• no inside interface (tun)
• no certificate state
• no firewall rules
• no connection manager

AI-assisted analysis of slackhq/nebula@dd8f660c0a (2026-09-03). Data as JSON: /api/errors/62a95ab8d6fddd0e. Report an issue: GitHub.