fatedier/frp · critical

create ssh gateway error, %v

Error message

create ssh gateway error, %v

What it means

When SSHTunnelGateway.BindPort > 0, frps builds an SSH gateway with ssh.NewGateway; failure aborts startup. The wrapped %v carries the underlying cause, typically listener or SSH key setup problems inside the gateway.

Source

Thrown at server/service.go:283

	if cfg.QUICBindPort > 0 {
		address := net.JoinHostPort(cfg.BindAddr, strconv.Itoa(cfg.QUICBindPort))
		quicTLSCfg := tlsConfig.Clone()
		quicTLSCfg.NextProtos = []string{"frp"}
		svr.quicListener, err = quic.ListenAddr(address, quicTLSCfg, &quic.Config{
			MaxIdleTimeout:     time.Duration(cfg.Transport.QUIC.MaxIdleTimeout) * time.Second,
			MaxIncomingStreams: int64(cfg.Transport.QUIC.MaxIncomingStreams),
			KeepAlivePeriod:    time.Duration(cfg.Transport.QUIC.KeepalivePeriod) * time.Second,
		})
		if err != nil {
			return nil, fmt.Errorf("listen on quic udp address %s error: %v", address, err)
		}
		log.Infof("frps quic listen on %s", address)
	}

	if cfg.SSHTunnelGateway.BindPort > 0 {
		sshGateway, err := ssh.NewGateway(cfg.SSHTunnelGateway, cfg.BindAddr, svr.sshTunnelListener)
		if err != nil {
			return nil, fmt.Errorf("create ssh gateway error: %v", err)
		}
		svr.sshTunnelGateway = sshGateway
		log.Infof("frps sshTunnelGateway listen on port %d", cfg.SSHTunnelGateway.BindPort)
	}

	// Listen for accepting connections from client using websocket protocol.
	websocketPrefix := []byte("GET " + netpkg.FrpWebsocketPath)
	websocketLn := svr.muxer.Listen(0, uint32(len(websocketPrefix)), func(data []byte) bool {
		return bytes.Equal(data, websocketPrefix)
	})
	svr.websocketListener = netpkg.NewWebsocketListener(websocketLn)

	// Create http vhost muxer.
	if cfg.VhostHTTPPort > 0 {
		rp := vhost.NewHTTPReverseProxy(vhost.HTTPReverseProxyOptions{
			ResponseHeaderTimeoutS: cfg.VhostHTTPTimeout,
		}, svr.httpVhostRouter)
		svr.rc.HTTPReverseProxy = rp

View on GitHub (pinned to 6c8a8d0a97)

Solutions

1. Read the wrapped cause in the log line to see if it is a bind or key problem
2. Free/change the SSH gateway bind port if it is a collision
3. Give frps a writable directory for SSH host keys
4. Remove the sshTunnelGateway section if the feature is unused

if err := service.New(cfg); err != nil && strings.Contains(err.Error(), "create ssh gateway error") {
    // inspect wrapped cause; fix key dir/port, then restart. Do not loop-retry.

When it happens

Trigger: Enabling the SSH tunnel gateway while its port or host-key resources are unavailable; a partially configured sshTunnelGateway section (missing/invalid authorized keys, key generation failure).

Common situations: Testing the ssh-tunnel visitor feature with incomplete gateway config; read-only filesystem preventing host-key creation; port collision for the gateway listener.

Related errors

• ps.Err
• create server listener error, %v
• create vhost tcpMuxer 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/350319ca3799dee1. Report an issue: GitHub.