ginuerzh/gost · error

socks5 UDP tunnel failure

Error message

socks5 UDP tunnel failure

What it means

Returned by the SOCKS5 UDP-over-TCP tunnel code when the server's reply to a CmdUDPTun associate request carries a Rep code other than Succeeded. The TCP control connection is fine, but the server refused to allocate the UDP relay endpoint, so no UDP tunnel can be established.

Source

Thrown at socks.go:1934

	req := gosocks5.NewRequest(CmdUDPTun, toSocksAddr(raddr))
	if err := req.Write(cc); err != nil {
		return nil, err
	}
	if Debug {
		log.Log("[socks5] udp-tun", req)
	}

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

	if Debug {
		log.Log("[socks5] udp-tun", reply)
	}

	if reply.Rep != gosocks5.Succeeded {
		return nil, errors.New("socks5 UDP tunnel failure")
	}

	baddr, err := net.ResolveUDPAddr("udp", reply.Addr.String())
	if err != nil {
		return nil, err
	}
	log.Logf("[socks5] udp-tun associate on %s OK", baddr)

	return &socks5UDPTunnelConn{
		Conn:  cc,
		taddr: taddr,
	}, nil
}

func (c *socks5UDPTunnelConn) Read(b []byte) (n int, err error) {
	n, _, err = c.ReadFrom(b)
	return
}

View on GitHub (pinned to a33fdbf4c9)

Solutions

1. Check whether the SOCKS5 server supports the UDP ASSOCIATE/udp-tun command
2. Verify the server's UDP relay port is open and not blocked by a firewall
3. Confirm server-side ACLs allow UDP relay for the requesting client
4. Retry against a different proxy node that permits UDP forwarding

When it happens

Trigger: Thrown at socks.go:1934 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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