fatedier/frp · critical

create vhost tcpMuxer error, %v

Error message

create vhost tcpMuxer error, %v

What it means

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.

Source

Thrown at server/service.go:201

		cfg:               cfg,
		ctx:               context.Background(),
	}
	if webServer != nil {
		webServer.RouteRegister(svr.registerRouteHandlers)
	}

	// Create tcpmux httpconnect multiplexer.
	if cfg.TCPMuxHTTPConnectPort > 0 {
		var l net.Listener
		address := net.JoinHostPort(cfg.ProxyBindAddr, strconv.Itoa(cfg.TCPMuxHTTPConnectPort))
		l, err = net.Listen("tcp", address)
		if err != nil {
			return nil, fmt.Errorf("create server listener error, %v", err)
		}

		svr.rc.TCPMuxHTTPConnectMuxer, err = tcpmux.NewHTTPConnectTCPMuxer(l, cfg.TCPMuxPassthrough, vhostReadWriteTimeout)
		if err != nil {
			return nil, fmt.Errorf("create vhost tcpMuxer error, %v", err)
		}
		log.Infof("tcpmux httpconnect multiplexer listen on %s, passthrough: %v", address, cfg.TCPMuxPassthrough)
	}

	// Init all plugins
	for _, p := range cfg.HTTPPlugins {
		svr.pluginManager.Register(plugin.NewHTTPPluginOptions(p))
		log.Infof("plugin [%s] has been registered", p.Name)
	}
	svr.rc.PluginManager = svr.pluginManager

	// Init group controller
	svr.rc.TCPGroupCtl = group.NewTCPGroupCtl(svr.rc.TCPPortManager)

	// Init HTTP group controller
	svr.rc.HTTPGroupCtl = group.NewHTTPGroupController(svr.httpVhostRouter)

	// Init TCP mux group controller

View on GitHub (pinned to 6c8a8d0a97)

Solutions

1. Re-run frps; if it reproduces, capture the wrapped %v cause in the log line and address that
2. Check file-descriptor limits (ulimit -n) on the host
3. As a workaround, disable tcpmuxHTTPConnectPort if you do not use httpconnect multiplexing

if err := svr.Start(); err != nil && strings.Contains(err.Error(), "create vhost tcpMuxer error") {
    // internal init failure on a good listener: one supervised restart is reasonable
}

When it happens

Trigger: NewHTTPConnectTCPMuxer failing during initialization (e.g. resource or internal state errors) immediately after the port was bound successfully.

Common situations: Exotic runtime conditions (fd exhaustion at startup, custom builds with modified tcpmux internals); almost never seen in stock deployments.

Related errors

• create vhost httpsMuxer error, %v
• unknown multiplexer [%s]
• create server listener error, %v
• listen on kcp udp address %s error: %v
• listen on quic udp address %s error: %v

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