fatedier/frp · critical

create vhost httpsMuxer error, %v

Error message

create vhost httpsMuxer error, %v

What it means

After the HTTPS port is bound, frps wraps the listener with vhost.NewHTTPSMuxer; a constructor failure aborts startup. As with the httpconnect muxer case, this is an internal setup failure on an already-valid listener and is rarely seen in stock deployments.

Source

Thrown at server/service.go:344

	}

	// Create https vhost muxer.
	if cfg.VhostHTTPSPort > 0 {
		var l net.Listener
		if httpsMuxOn {
			l = svr.muxer.ListenHTTPS(1)
		} else {
			address := net.JoinHostPort(cfg.ProxyBindAddr, strconv.Itoa(cfg.VhostHTTPSPort))
			l, err = net.Listen("tcp", address)
			if err != nil {
				return nil, fmt.Errorf("create server listener error, %v", err)
			}
			log.Infof("https service listen on %s", address)
		}

		svr.rc.VhostHTTPSMuxer, err = vhost.NewHTTPSMuxer(l, vhostReadWriteTimeout)
		if err != nil {
			return nil, fmt.Errorf("create vhost httpsMuxer error, %v", err)
		}

		// Init HTTPS group controller after HTTPSMuxer is created
		svr.rc.HTTPSGroupCtl = group.NewHTTPSGroupController(svr.rc.VhostHTTPSMuxer)
	}

	// frp tls listener
	svr.tlsListener = svr.muxer.Listen(2, 1, func(data []byte) bool {
		// tls first byte can be 0x16 only when vhost https port is not same with bind port
		return int(data[0]) == netpkg.FRPTLSHeadByte || int(data[0]) == 0x16
	})

	// Create nat hole controller.
	nc, err := nathole.NewController(time.Duration(cfg.NatHoleAnalysisDataReserveHours) * time.Hour)
	if err != nil {
		return nil, fmt.Errorf("create nat hole controller error, %v", err)
	}
	svr.rc.NatHoleController = nc

View on GitHub (pinned to 6c8a8d0a97)

Solutions

1. Retry starting frps; if persistent, extract the wrapped %v cause and fix that
2. Raise file-descriptor limits on the host
3. Disable vhostHTTPSPort if HTTPS vhost routing is not required

if err := newService(cfg); err != nil && strings.Contains(err.Error(), "create vhost httpsMuxer error") {
    // internal init failure after successful bind: supervised single retry, then report
}

When it happens

Trigger: NewHTTPSMuxer failing during its internal initialization immediately after a successful net.Listen.

Common situations: Resource pressure at boot (fd limits), forks with modified vhost internals; essentially never triggered by user config.

Related errors

• create vhost tcpMuxer error, %v
• create vhost http listener error, %v
• 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/45ee2fa936de938f. Report an issue: GitHub.