netbirdio/netbird · error · ErrInvalidTunnelFD

invalid tunnel file descriptor: fd is 0 (Swift failed to loc

Error message

invalid tunnel file descriptor: fd is 0 (Swift failed to locate utun socket)

What it means

Error "invalid tunnel file descriptor: fd is 0 (Swift failed to locate utun socket)" thrown in netbirdio/netbird.

Source

Thrown at client/iface/device/device_ios.go:48

	udpMux         *udpmux.UniversalUDPMuxDefault
	configurer     WGConfigurer
}

func NewTunDevice(name string, address wgaddr.Address, port int, key string, mtu uint16, iceBind *bind.ICEBind, tunFd int) *TunDevice {
	return &TunDevice{
		name:    name,
		address: address,
		port:    port,
		key:     key,
		mtu:     mtu,
		iceBind: iceBind,
		tunFd:   tunFd,
	}
}

// ErrInvalidTunnelFD is returned when the tunnel file descriptor is invalid (0).
// This typically means the Swift code couldn't find the utun control socket.
var ErrInvalidTunnelFD = fmt.Errorf("invalid tunnel file descriptor: fd is 0 (Swift failed to locate utun socket)")

func (t *TunDevice) Create() (WGConfigurer, error) {
	log.Infof("create tun interface")

	var tunDevice tun.Device
	var err error

	// Validate the tunnel file descriptor.
	// On iOS/tvOS, the FD must be provided by the NEPacketTunnelProvider.
	// A value of 0 means the Swift code couldn't find the utun control socket
	// (the low-level APIs like ctl_info, sockaddr_ctl may not be exposed in
	// tvOS SDK headers). This is a hard error - there's no viable fallback
	// since tun.CreateTUN() cannot work within the iOS/tvOS sandbox.
	if t.tunFd == 0 {
		log.Errorf("Tunnel file descriptor is 0 - Swift code failed to locate the utun control socket. " +
			"On tvOS, ensure the NEPacketTunnelProvider is properly configured and the tunnel is started.")
		return nil, ErrInvalidTunnelFD
	}

View on GitHub (pinned to 93e97f4bf1)

When it happens

Trigger: Thrown at client/iface/device/device_ios.go:48 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of netbirdio/netbird@93e97f4bf1 (2026-08-16). Data as JSON: /api/errors/8775dbbc00476ab0. Report an issue: GitHub.