What causes "SOCKS5 udp relay failure" in ginuerzh/gost?

Enable UDP relay on the proxy server (e.g. allow udp in its config) or pick a proxy that supports UDP ASSOCIATE.

SOCKS5 udp relay failure

Error message

SOCKS5 udp relay failure

What it means

The SOCKS5 UDP ASSOCIATE request was rejected by the proxy: gosocks5.ReadReply returned a reply whose Rep is not Succeeded. The library converts the server's refusal into this error instead of a UDP relay connection.

Source

Thrown at socks.go:615

		return nil, err
	}

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

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

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

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

	uc, err := net.DialUDP("udp", nil, baddr)
	if err != nil {
		return nil, err
	}
	// log.Logf("udp laddr:%s, raddr:%s", uc.LocalAddr(), uc.RemoteAddr())

	return &socks5UDPConn{UDPConn: uc, taddr: taddr}, nil
}

type socks5UDPTunConnector struct {
	User *url.Userinfo

View on GitHub (pinned to a33fdbf4c9)

Solutions

Enable UDP relay on the proxy server (e.g. allow udp in its config) or pick a proxy that supports UDP ASSOCIATE.
Ensure the TCP control connection originates from the same address the proxy expects for the UDP relay.
Check firewall rules allow the UDP ports the proxy replies with.
Fall back to TCP-based connectors (socks5/tls) if UDP relay is not required.

Example fix

// before
c := socks5UDPConnector{} // server: udp-relay disabled -> "SOCKS5 udp relay failure"
// after
serverCfg := "udp-relay: true" // enable on proxy, or use Socks5Connector() over TCP

Defensive patterns

Strategy: try-catch

Validate before calling

// Ensure the control conn is TCP-capable before UDP ASSOCIATE
if _, ok := ctrlConn.(*net.TCPConn); !ok {
	return errors.New("udp associate requires a TCP control connection")
}

Try / catch

relay, err := udpConnector.ConnectContext(ctx, ctrlConn, "udp", addr)
if err != nil {
	if strings.Contains(err.Error(), "udp relay failure") {
		// proxy refused ASSOCIATE: check server udp-relay config, fall back to TCP
		return tcpFallback(ctx, addr)
	}
	return err
}

Prevention

Enable UDP relay on the proxy server config.
Ensure the client IP matches the ASSOCIATE-declared address (no double NAT surprises).
Open firewall ports for the proxy's UDP relay range.
Probe UDP support once at startup and cache the capability.

When it happens

Trigger: socks5UDPConnector.ConnectContext with a udp-family network sends the SOCKS5 UDP ASSOCIATE request; the server answers with a failure reply (UDP relay not allowed, client address mismatch, server lacks UDP support).

Common situations: Proxy server has UDP relay disabled (common on hardened or commercial proxies); client's source IP differs from the address declared in the associate request (proxy rejects); firewall blocks the UDP relay port range.

Related errors

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