fatedier/frp · error

initial client session error: %v

Error message

initial client session error: %v

What it means

KCPTunnelSession.Init failed at fmux.Client(remote, fmuxCfg), creating the yamux-style multiplexed session over the freshly created KCP connection. With these configs (10 s keepalive, 6 MB window) the constructor rarely fails; an error means the multiplexer handshake over the KCP stream could not complete.

Source

Thrown at client/visitor/xtcp.go:357

	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
}

func (ks *KCPTunnelSession) OpenConn(_ context.Context) (net.Conn, error) {
	ks.mu.RLock()
	defer ks.mu.RUnlock()
	session := ks.session
	if session == nil {
		return nil, ErrNoTunnelSession
	}
	return session.Open()
}

View on GitHub (pinned to 6c8a8d0a97)

Solutions

1. Confirm both endpoints run the same frp release; multiplexer handshake incompatibilities are the top cause.
2. Retest NAT behavior; if either side is symmetric NAT, xtcp will not converge, so use stcp instead.
3. Allow UDP in both directions for the data path, not just STUN.
4. Retry a few times; punched mappings are short-lived and the first attempt can race the mapping expiry.

When it happens

Trigger: fmux.Client returns an error when the initial handshake write/read over the KCP conn fails: the peer is not speaking fmux (version mismatch), the NAT hole actually closed, or the remote xtcp owner is not listening for KCP traffic on the punched mapping.

Common situations: frpc/frps version skew (fmux config incompatibility); hole punch succeeded at the STUN level but the data path is one-way (symmetric NAT on the peer); firewall dropping the larger initial frames (6 MB window advertisement).

Related errors

• dial udp error: %v
• create kcp connection from udp connection error: %v
• ErrNoTunnelSession
• unknown proxy config type
• open tunnel timeout

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