{"record":{"id":"cdf525980b99a849","repo":"fatedier/frp","slug":"create-server-listener-error-v","errorCode":null,"errorMessage":"create server listener error, %v","messagePattern":"create server listener error, (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/service.go","lineNumber":196,"sourceCode":"\t\tsshTunnelListener: netpkg.NewInternalListener(),\n\t\thttpVhostRouter:   vhost.NewRouters(),\n\t\tauth:              authRuntime,\n\t\twebServer:         webServer,\n\t\ttlsConfig:         tlsConfig,\n\t\tcfg:               cfg,\n\t\tctx:               context.Background(),\n\t}\n\tif webServer != nil {\n\t\twebServer.RouteRegister(svr.registerRouteHandlers)\n\t}\n\n\t// Create tcpmux httpconnect multiplexer.\n\tif cfg.TCPMuxHTTPConnectPort > 0 {\n\t\tvar l net.Listener\n\t\taddress := net.JoinHostPort(cfg.ProxyBindAddr, strconv.Itoa(cfg.TCPMuxHTTPConnectPort))\n\t\tl, err = net.Listen(\"tcp\", address)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"create server listener error, %v\", err)\n\t\t}\n\n\t\tsvr.rc.TCPMuxHTTPConnectMuxer, err = tcpmux.NewHTTPConnectTCPMuxer(l, cfg.TCPMuxPassthrough, vhostReadWriteTimeout)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"create vhost tcpMuxer error, %v\", err)\n\t\t}\n\t\tlog.Infof(\"tcpmux httpconnect multiplexer listen on %s, passthrough: %v\", address, cfg.TCPMuxPassthrough)\n\t}\n\n\t// Init all plugins\n\tfor _, p := range cfg.HTTPPlugins {\n\t\tsvr.pluginManager.Register(plugin.NewHTTPPluginOptions(p))\n\t\tlog.Infof(\"plugin [%s] has been registered\", p.Name)\n\t}\n\tsvr.rc.PluginManager = svr.pluginManager\n\n\t// Init group controller\n\tsvr.rc.TCPGroupCtl = group.NewTCPGroupCtl(svr.rc.TCPPortManager)","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/fatedier/frp/blob/6c8a8d0a97d03b44e9528d30b30c70cb9d61b405/server/service.go#L178-L214","documentation":"During frps startup, when tcpmuxHTTPConnectPort > 0 the server tries to net.Listen on ProxyBindAddr:TCPMuxHTTPConnectPort. Any bind failure (port in use, permission denied, bad address) aborts service creation with this error, so frps exits before serving anything.","triggerScenarios":"Another process already listening on the tcpmux httpconnect port; binding a privileged port (<1024) as non-root; ProxyBindAddr set to an IP not present on the machine.","commonSituations":"Port collision with another frps instance or service; hardened/container environments blocking low ports; typo in bind address.","solutions":["Free the port or pick another tcpmuxHTTPConnectPort","If binding <1024, run with adequate capability (setcap/cap_net_bind_service) or choose a high port","Verify ProxyBindAddr is a local interface IP or 0.0.0.0"],"exampleFix":"# before\ntcpmuxHTTPConnectPort = 443   # permission denied as non-root\n\n# after\ntcpmuxHTTPConnectPort = 12443","handlingStrategy":"validation","validationCode":"// Pre-flight the port before frps tries to bind it.\nfunc portFree(network, addr string) bool {\n    l, err := net.Listen(network, addr)\n    if err != nil { return false }\n    l.Close()\n    return true\n}\nif !portFree(\"tcp\", fmt.Sprintf(\"%s:%d\", cfg.ProxyBindAddr, cfg.TCPMuxHTTPConnectPort)) {\n    return fmt.Errorf(\"tcpmux port %d already in use\", cfg.TCPMuxHTTPConnectPort)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Maintain one authoritative list of ports per host and check it in config management","Run frps under a supervisor that surfaces startup bind failures loudly","Avoid privileged ports unless the process has cap_net_bind_service"],"tags":["frps","startup","network","port"],"backgroundTag":null,"analyzedSha":"6c8a8d0a97d03b44e9528d30b30c70cb9d61b405","analyzedAt":"2026-08-15T06:53:27.215Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}