{"record":{"id":"82c33ed8d7b8952e","repo":"fatedier/frp","slug":"listen-on-kcp-udp-address-s-error-v","errorCode":null,"errorMessage":"listen on kcp udp address %s error: %v","messagePattern":"listen on kcp udp address (.+?) error: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/service.go","lineNumber":260,"sourceCode":"\t\treturn nil, fmt.Errorf(\"create server listener error, %v\", err)\n\t}\n\n\tsvr.muxer = mux.NewMux(ln)\n\tsvr.muxer.SetKeepAlive(time.Duration(cfg.Transport.TCPKeepAlive) * time.Second)\n\tgo func() {\n\t\t_ = svr.muxer.Serve()\n\t}()\n\tln = svr.muxer.DefaultListener()\n\n\tsvr.listener = ln\n\tlog.Infof(\"frps tcp listen on %s\", address)\n\n\t// Listen for accepting connections from client using kcp protocol.\n\tif cfg.KCPBindPort > 0 {\n\t\taddress := net.JoinHostPort(cfg.BindAddr, strconv.Itoa(cfg.KCPBindPort))\n\t\tsvr.kcpListener, err = netpkg.ListenKcp(address)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"listen on kcp udp address %s error: %v\", address, err)\n\t\t}\n\t\tlog.Infof(\"frps kcp listen on udp %s\", address)\n\t}\n\n\tif cfg.QUICBindPort > 0 {\n\t\taddress := net.JoinHostPort(cfg.BindAddr, strconv.Itoa(cfg.QUICBindPort))\n\t\tquicTLSCfg := tlsConfig.Clone()\n\t\tquicTLSCfg.NextProtos = []string{\"frp\"}\n\t\tsvr.quicListener, err = quic.ListenAddr(address, quicTLSCfg, &quic.Config{\n\t\t\tMaxIdleTimeout:     time.Duration(cfg.Transport.QUIC.MaxIdleTimeout) * time.Second,\n\t\t\tMaxIncomingStreams: int64(cfg.Transport.QUIC.MaxIncomingStreams),\n\t\t\tKeepAlivePeriod:    time.Duration(cfg.Transport.QUIC.KeepalivePeriod) * time.Second,\n\t\t})\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"listen on quic udp address %s error: %v\", address, err)\n\t\t}\n\t\tlog.Infof(\"frps quic listen on %s\", address)\n\t}","sourceCodeStart":242,"sourceCodeEnd":278,"githubUrl":"https://github.com/fatedier/frp/blob/6c8a8d0a97d03b44e9528d30b30c70cb9d61b405/server/service.go#L242-L278","documentation":"When KCPBindPort > 0, frps opens a UDP listener for the KCP transport via netpkg.ListenKcp. Failure aborts startup with the offending address included. Like the TCP bind, this is fatal: the server process will not come up.","triggerScenarios":"Another UDP service on the same KCPBindPort; firewall/SELinux blocking UDP bind; BindAddr misconfigured; a previous frps still holding the socket.","commonSituations":"kcpBindPort collides with another UDP service (Quake-style servers, DTLS, DNS on odd ports); cloud environments filtering UDP; duplicated frps instances.","solutions":["Check ss -uln for the port and stop the conflicting process","Pick a different kcpBindPort and mirror it in every frpc using protocol = kcp","If UDP is blocked in the environment, remove kcpBindPort and use tcp/quan","Verify firewall rules allow inbound UDP on that port"],"exampleFix":"# before\nkcpBindPort = 7000   # UDP already bound\n\n# after\nkcpBindPort = 7100","handlingStrategy":"validation","validationCode":"if c, err := net.ListenPacket(\"udp\", fmt.Sprintf(\"%s:%d\", cfg.BindAddr, cfg.KCPBindPort)); err != nil {\n    return fmt.Errorf(\"kcp udp port %d unavailable: %w\", cfg.KCPBindPort, err)\n} else { c.Close() }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Verify UDP sockets are allowed in the host/container before enabling KCP","Prefer unique high ports for kcpBindPort to avoid common UDP collisions","Keep an automatic fallback to tcp transport in client configs when kcp is unavailable"],"tags":["frps","startup","kcp","udp","port"],"backgroundTag":null,"analyzedSha":"6c8a8d0a97d03b44e9528d30b30c70cb9d61b405","analyzedAt":"2026-08-15T06:53:27.215Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}