What causes "SOCKS5 bind on %s failure" in ginuerzh/gost?

Inspect the proxy's debug log and its access rules; allow the BIND command and the requested address in the proxy ACL.

SOCKS5 bind on %s failure

Error message

SOCKS5 bind on %s failure

What it means

The SOCKS5 BIND request (gosocks5.CmdBind) sent to the proxy was rejected: the server replied with a reply code other than gosocks5.Succeeded. The library surfaces the server's refusal as this error instead of returning a connection, because the remote endpoint refused or could not perform the TCP bind (reverse connection) for the requested address.

Source

Thrown at socks.go:360

		return nil, err
	}

	if Debug {
		log.Log("[socks5] bind\n", req)
	}

	reply, err := gosocks5.ReadReply(conn)
	if err != nil {
		return nil, err
	}

	if Debug {
		log.Log("[socks5] bind\n", reply)
	}

	if reply.Rep != gosocks5.Succeeded {
		log.Logf("[socks5] bind on %s failure", address)
		return nil, fmt.Errorf("SOCKS5 bind on %s failure", address)
	}
	baddr, err := net.ResolveTCPAddr("tcp", reply.Addr.String())
	if err != nil {
		return nil, err
	}
	log.Logf("[socks5] bind on %s OK", baddr)

	return &socks5BindConn{Conn: conn, laddr: baddr}, nil
}

type socks5MuxBindConnector struct{}

// Socks5MuxBindConnector creates a Connector for SOCKS5 multiplex bind client.
func Socks5MuxBindConnector() Connector {
	return &socks5MuxBindConnector{}
}

func (c *socks5MuxBindConnector) Connect(conn net.Conn, address string, options ...ConnectOption) (net.Conn, error) {

View on GitHub (pinned to a33fdbf4c9)

Solutions

Inspect the proxy's debug log and its access rules; allow the BIND command and the requested address in the proxy ACL.
Verify the address string passed to ConnectContext is a valid host:port reachable/allowed by the proxy.
Use a CONNECT-based connector (Socks5Connector) instead if you do not actually need a reverse bind.
Ensure the client that must connect back to the bound port can reach the proxy's external IP (NAT/firewall).

Example fix

// before
conn, err := bindConnector.ConnectContext(ctx, proxyConn, "tcp", "0.0.0.0:0")
// after
if _, port, _ := net.SplitHostPort(addr); port == "0" { /* let proxy choose; check ACLs */ }
conn, err := socks5Connector.ConnectContext(ctx, proxyConn, "tcp", target) // if reverse bind not needed

Defensive patterns

Strategy: try-catch

Validate before calling

host, port, err := net.SplitHostPort(address)
if err != nil || host == "" || port == "" {
	return fmt.Errorf("invalid bind address %q", address)
}

Type guard

func isTCPFamily(network string) bool {
	switch network {
	case "tcp", "tcp4", "tcp6":
		return true
	}
	return false
}

Try / catch

conn, err := bindConnector.ConnectContext(ctx, proxyConn, "tcp", addr)
if err != nil {
	if strings.Contains(err.Error(), "bind on") {
		// proxy refused BIND: log reply details, fall back to CONNECT
		return fallbackConnect(ctx, addr)
	}
	return err
}

Prevention

Only use BIND when you truly need a reverse connection; prefer CONNECT.
Confirm the proxy supports and permits the BIND command before deploying.
Pre-verify the bind address format with net.ResolveTCPAddr.
Ensure the peer that connects back can reach the proxy's external IP.

When it happens

Trigger: Calling Socks5BindConnector().ConnectContext (via Connect) with a tcp-family network and a bind address; the proxy responds to the BIND request with a non-Succeeded reply (e.g. connection/binding not allowed by proxy rules, port unavailable, or the target host failed to connect back).

Common situations: Trying to use SOCKS5 BIND for NAT traversal or reverse connections where the proxy disallows BIND; proxy ACLs rejecting the bind address; requesting a specific bind port already in use; proxies that simply do not support the BIND command.

Related errors

AI-assisted analysis of ginuerzh/gost@a33fdbf4c9 (2026-09-02). Data as JSON: /api/errors/2ff9e83d7d5f26ee. Report an issue: GitHub.