jstedfast/MailKit · error · ProxyProtocolException

Proxy server responded with unknown SOCKS version

Error message

Proxy server responded with unknown SOCKS version: {0}

What it means

During SOCKS5 handshake the server must echo protocol version 5 in its responses. VerifySocksVersion throws ProxyProtocolException when the version byte differs, meaning the endpoint is not behaving as a SOCKS5 proxy (wrong service, an HTTP proxy, a captive portal, or garbage).

Solutions

Confirm the proxy port is actually SOCKS5 (e.g. curl --socks5 host:port) and fix the port in configuration
If the proxy is SOCKS5 over TLS, wrap the connection in SSL before/with the proxy client as documented
Check for interception devices/firewalls rewriting the response; test from an unrestricted network

Example fix

// before
proxyClient.ProxyClient = new Socks5Client { ProxyHost = "proxy", ProxyPort = 3128 }; // HTTP proxy port
// after
proxyClient.ProxyClient = new Socks5Client { ProxyHost = "proxy", ProxyPort = 1080 }; // real SOCKS5 port

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-flight outside the app:
// printf '\x05\x01\x00' | nc proxy 1080 | xxd  # first byte must be 0x05

Try / catch

try {
    await socks5.ConnectAsync(proxyHost, proxyPort, target, targetPort);
} catch (ProxyProtocolException ex) when (ex.Message.Contains("unknown SOCKS version")) {
    log.Error("Endpoint {0}:{1} is not SOCKS5 — check proxy type/port/TLS", proxyHost, proxyPort);
}

Prevention

Keep SOCKS5 and HTTP proxy ports distinct in configuration
Remember SOCKS5-over-TLS needs SSL wrapping first
Test proxy type with curl --socks5 during environment provisioning

When it happens

Trigger: Calling Socks5Client.Connect/ConnectAsync against a server that is not SOCKS5: pointed at an HTTP proxy port, a TLS-wrapped SOCKS endpoint, or a plain web server; also when responses get corrupted mid-stream (ProcessPartialConnectResponse).

Common situations: Config mistake mixing up proxy ports (SOCKS5 client pointed at an HTTP CONNECT port 3128/8080), proxy behind TLS requiring SslStream wrapping first, or transparent proxies returning HTML error pages.

Related errors

AI-assisted analysis of jstedfast/MailKit@9d3859a785 (2026-09-15). Data as JSON: /api/errors/1a99073307e9205e. Report an issue: GitHub.

Appendix: source

Thrown at MailKit/Net/Proxy/Socks5Client.cs:172

			}
		}

		internal static Socks5AddressType GetAddressType (string host, out IPAddress? ip)
		{
			if (!IPAddress.TryParse (host, out ip))
				return Socks5AddressType.Domain;

			switch (ip.AddressFamily) {
			case AddressFamily.InterNetworkV6: return Socks5AddressType.IPv6;
			case AddressFamily.InterNetwork: return Socks5AddressType.IPv4;
			default: throw new ArgumentException ("The host address must be an IPv4 or IPv6 address.", nameof (host));
			}
		}

		void VerifySocksVersion (byte version)
		{
			if (version != (byte) SocksVersion)
				throw new ProxyProtocolException (string.Format (CultureInfo.InvariantCulture, "Proxy server responded with unknown SOCKS version: {0}", (int) version));
		}

		byte[] GetNegotiateAuthMethodCommand (Socks5AuthMethod[] methods)
		{
			// +-----+----------+----------+
			// | VER | NMETHODS | METHODS  |
			// +-----+----------+----------+
			// |  1  |    1     | 1 to 255 |
			// +-----+----------+----------+
			var buffer = new byte[2 + methods.Length];
			int n = 0;

			buffer[n++] = (byte) SocksVersion;
			buffer[n++] = (byte) methods.Length;
			for (int i = 0; i < methods.Length; i++)
				buffer[n++] = (byte) methods[i];

			return buffer;

View on GitHub (pinned to 9d3859a785)