fatedier/frp · error

create kcp connection from udp connection error: %v

Error message

create kcp connection from udp connection error: %v

What it means

After successfully dialing the UDP socket, netpkg.NewKCPConnFromUDP failed to wrap it into a KCP connection toward the peer. The underlying UDP socket is closed before returning; the failure is in constructing the KCP state machine for the new socket.

Source

Thrown at client/visitor/xtcp.go:347

	lConn   *net.UDPConn
	mu      sync.RWMutex
}

func NewKCPTunnelSession() TunnelSession {
	return &KCPTunnelSession{}
}

func (ks *KCPTunnelSession) Init(listenConn *net.UDPConn, raddr *net.UDPAddr) error {
	listenConn.Close()
	laddr, _ := net.ResolveUDPAddr("udp", listenConn.LocalAddr().String())
	lConn, err := net.DialUDP("udp", laddr, raddr)
	if err != nil {
		return fmt.Errorf("dial udp error: %v", err)
	}
	remote, err := netpkg.NewKCPConnFromUDP(lConn, true, raddr.String())
	if err != nil {
		lConn.Close()
		return fmt.Errorf("create kcp connection from udp connection error: %v", err)
	}

	fmuxCfg := fmux.DefaultConfig()
	fmuxCfg.KeepAliveInterval = 10 * time.Second
	fmuxCfg.MaxStreamWindowSize = 6 * 1024 * 1024
	fmuxCfg.LogOutput = io.Discard
	session, err := fmux.Client(remote, fmuxCfg)
	if err != nil {
		remote.Close()
		return fmt.Errorf("initial client session error: %v", err)
	}
	ks.mu.Lock()
	ks.session = session
	ks.lConn = lConn
	ks.mu.Unlock()
	return nil
}

View on GitHub (pinned to 6c8a8d0a97)

Solutions

1. Verify the nathole discovery output: the external address of each peer must be routable from this host (check IPv4/IPv6 availability).
2. Ensure frpc and frps run compatible versions; KCP framing changed across releases.
3. Retry the connection; transient allocation failures clear under lighter load.
4. If one side lacks IPv6, force IPv4 in the STUN/nathole flow and retry.

When it happens

Trigger: NewKCPConnFromUDP(lConn, true, raddr.String()) returns an error: an internal allocation/initialization failure or an invalid remote address string after the NAT exchange produced an unusable raddr.

Common situations: Corrupted or unroutable raddr from nathole coordination (e.g., IPv6 address on a host without IPv6); resource exhaustion during session setup; KCP wrapper version mismatch between frpc and frps.

Related errors

• open tunnel timeout
• dial udp error: %v
• dial quic error: %v
• initial client session error: %v
• wait detect message error: %v

AI-assisted analysis of fatedier/frp@6c8a8d0a97 (2026-08-15). Data as JSON: /api/errors/712d3d9ea7fda717. Report an issue: GitHub.