jstedfast/MailKit · error · ArgumentException

The host address must be an IPv4 or IPv6 address.

Error message

The host address must be an IPv4 or IPv6 address.

What it means

Socks5Client.GetAddressType classifies the host string; if IPAddress.TryParse succeeds but yields an AddressFamily other than IPv4/IPv6 (defensive branch), the client cannot encode it in the SOCKS5 connect request and throws an ArgumentException. In practice this is nearly unreachable and signals a malformed/unsupported address string.

Solutions

1. Pass a plain hostname, a standard dotted-quad IPv4 literal, or a normal IPv6 literal as host
2. If you already have an IPAddress object, verify ip.AddressFamily is InterNetwork or InterNetworkV6 before calling
3. Upgrade MailKit; newer IPAddress.TryParse behavior may have caused this on specific runtimes

if (IPAddress.TryParse(host, out var ip)
    && ip.AddressFamily != AddressFamily.InterNetwork
    && ip.AddressFamily != AddressFamily.InterNetworkV6)
    throw new ArgumentException("Host must be a hostname or IPv4/IPv6 literal.", nameof(host));

static bool IsSock5EncodableHost(string host) =>
    !IPAddress.TryParse(host, out var ip)
    || ip.AddressFamily is AddressFamily.InterNetwork or AddressFamily.InterNetworkV6;

When it happens

Trigger: Calling Socks5Client.ConnectAsync with a host string that parses as an IPAddress but is neither IPv4 nor IPv6 (edge-case parse results); ordinary domains and IPv4/IPv6 literals never hit it.

Common situations: Passing odd address-like strings (e.g. numeric forms) that the platform's IPAddress.TryParse accepts on some framework versions but the SOCKS encoder does not support.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• The header field is invalid.
• One or more of the headers is invalid.
• The host name cannot be empty.
• The socket is not connected.
• The doneToken must be cancellable.

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

Appendix: source

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

			case Socks5Reply.NetworkUnreachable:      return "Network unreachable.";
			case Socks5Reply.HostUnreachable:         return "Host unreachable.";
			case Socks5Reply.ConnectionRefused:       return "Connection refused.";
			case Socks5Reply.TTLExpired:              return "TTL expired.";
			case Socks5Reply.CommandNotSupported:     return "Command not supported.";
			case Socks5Reply.AddressTypeNotSupported: return "Address type not supported.";
			default:                                  return string.Format (CultureInfo.InvariantCulture, "Unknown error ({0}).", (int) reply);
			}
		}

		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;

View on GitHub (pinned to 9d3859a785)