{"record":{"id":"75a9a7398ca10d50","repo":"fatedier/frp","slug":"create-vhost-tcpmuxer-error-v","errorCode":null,"errorMessage":"create vhost tcpMuxer error, %v","messagePattern":"create vhost tcpMuxer error, (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/service.go","lineNumber":201,"sourceCode":"\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)\n\n\t// Init HTTP group controller\n\tsvr.rc.HTTPGroupCtl = group.NewHTTPGroupController(svr.httpVhostRouter)\n\n\t// Init TCP mux group controller","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/fatedier/frp/blob/6c8a8d0a97d03b44e9528d30b30c70cb9d61b405/server/service.go#L183-L219","documentation":"After successfully opening the tcpmux listener, frps wraps it with tcpmux.NewHTTPConnectTCPMuxer; if that constructor fails, service creation aborts. This is an internal setup failure of the httpconnect multiplexer rather than a bind problem, and in practice is rarely hit because the underlying listener is already valid.","triggerScenarios":"NewHTTPConnectTCPMuxer failing during initialization (e.g. resource or internal state errors) immediately after the port was bound successfully.","commonSituations":"Exotic runtime conditions (fd exhaustion at startup, custom builds with modified tcpmux internals); almost never seen in stock deployments.","solutions":["Re-run frps; if it reproduces, capture the wrapped %v cause in the log line and address that","Check file-descriptor limits (ulimit -n) on the host","As a workaround, disable tcpmuxHTTPConnectPort if you do not use httpconnect multiplexing"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := svr.Start(); err != nil && strings.Contains(err.Error(), \"create vhost tcpMuxer error\") {\n    // internal init failure on a good listener: one supervised restart is reasonable\n}","preventionTips":["Raise ulimit -n on hosts running frps","If tcpmux httpconnect is unused, leave tcpmuxHTTPConnectPort unset to remove the whole failure class"],"tags":["frps","startup","tcpmux","internal"],"backgroundTag":null,"analyzedSha":"6c8a8d0a97d03b44e9528d30b30c70cb9d61b405","analyzedAt":"2026-08-15T06:53:27.215Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}