{"record":{"id":"712d3d9ea7fda717","repo":"fatedier/frp","slug":"create-kcp-connection-from-udp-connection-error","errorCode":null,"errorMessage":"create kcp connection from udp connection error: %v","messagePattern":"create kcp connection from udp connection error: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/visitor/xtcp.go","lineNumber":347,"sourceCode":"\tlConn   *net.UDPConn\n\tmu      sync.RWMutex\n}\n\nfunc NewKCPTunnelSession() TunnelSession {\n\treturn &KCPTunnelSession{}\n}\n\nfunc (ks *KCPTunnelSession) Init(listenConn *net.UDPConn, raddr *net.UDPAddr) error {\n\tlistenConn.Close()\n\tladdr, _ := net.ResolveUDPAddr(\"udp\", listenConn.LocalAddr().String())\n\tlConn, err := net.DialUDP(\"udp\", laddr, raddr)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"dial udp error: %v\", err)\n\t}\n\tremote, err := netpkg.NewKCPConnFromUDP(lConn, true, raddr.String())\n\tif err != nil {\n\t\tlConn.Close()\n\t\treturn fmt.Errorf(\"create kcp connection from udp connection error: %v\", err)\n\t}\n\n\tfmuxCfg := fmux.DefaultConfig()\n\tfmuxCfg.KeepAliveInterval = 10 * time.Second\n\tfmuxCfg.MaxStreamWindowSize = 6 * 1024 * 1024\n\tfmuxCfg.LogOutput = io.Discard\n\tsession, err := fmux.Client(remote, fmuxCfg)\n\tif err != nil {\n\t\tremote.Close()\n\t\treturn fmt.Errorf(\"initial client session error: %v\", err)\n\t}\n\tks.mu.Lock()\n\tks.session = session\n\tks.lConn = lConn\n\tks.mu.Unlock()\n\treturn nil\n}\n","sourceCodeStart":329,"sourceCodeEnd":365,"githubUrl":"https://github.com/fatedier/frp/blob/6c8a8d0a97d03b44e9528d30b30c70cb9d61b405/client/visitor/xtcp.go#L329-L365","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the nathole discovery output: the external address of each peer must be routable from this host (check IPv4/IPv6 availability).","Ensure frpc and frps run compatible versions; KCP framing changed across releases.","Retry the connection; transient allocation failures clear under lighter load.","If one side lacks IPv6, force IPv4 in the STUN/nathole flow and retry."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":["Confirm IPv4/IPv6 availability matches the nathole-discovered addresses","Pin both ends to the same frp version"],"tags":["xtcp","kcp","udp","nat"],"backgroundTag":null,"analyzedSha":"6c8a8d0a97d03b44e9528d30b30c70cb9d61b405","analyzedAt":"2026-08-15T06:53:27.215Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}