jstedfast/MailKit · error · ArgumentException

The length of the host name must be between 0 and 256…

Error message

The length of the host name must be between 0 and 256 characters.

What it means

The protected ProxyClient constructor validates the proxy host name: it must be non-null, non-empty, and at most 255 characters, otherwise ArgumentException('The length of the host name must be between 0 and 256 characters.') is thrown (ArgumentNullException for null). This runs when constructing any proxy client (Http, Socks4/5).

Solutions

1. Validate the proxy host from configuration before constructing: it must be non-empty and <= 255 chars.
2. Check where the value is read (env var / appSettings) for empty or missing values and fail fast with a clear config error.
3. If no proxy is needed, do not construct a ProxyClient at all instead of passing an empty host.
4. Trim whitespace and re-validate; a whitespace-only string still effectively fails the connection.

Example fix

// before
var proxy = new Socks5Client(config.ProxyHost, config.ProxyPort); // ProxyHost == ""
// after
if (string.IsNullOrWhiteSpace(config.ProxyHost) || config.ProxyHost.Length > 255)
    throw new InvalidOperationException("PROXY_HOST is missing or invalid");
var proxy = new Socks5Client(config.ProxyHost.Trim(), config.ProxyPort);

if (string.IsNullOrWhiteSpace(host) || host.Length > 255)
    throw new InvalidOperationException("Proxy host missing or too long in configuration");

bool IsValidProxyHost(string? h) => !string.IsNullOrWhiteSpace(h) && h.Length <= 255;

try {
    var proxy = new HttpProxyClient(host, port);
} catch (ArgumentException ex) when (ex.ParamName == "host") {
    // fall back to direct connection or surface a config error
}

When it happens

Trigger: Constructing Socks4Client/Socks5Client/HttpProxyClient with host = "" or a string longer than 255 chars — usually an empty config/environment variable silently substituted for the proxy host.

Common situations: Missing PROXY_HOST env var read as string.Empty; copy-paste or trimming bug producing an empty host; config file where the proxy section is blank; unlikely >255-char host from malformed data.

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 specified host address must be IPv4.
• The host name cannot be empty.
• array
• uri
• visitor

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

Appendix: source

Thrown at MailKit/Net/Proxy/ProxyClient.cs:96

		/// <param name="port">The proxy server port.</param>
		/// <exception cref="System.ArgumentNullException">
		/// <paramref name="host"/> is <see langword="null" />.
		/// </exception>
		/// <exception cref="System.ArgumentOutOfRangeException">
		/// <paramref name="port"/> is not between <c>0</c> and <c>65535</c>.
		/// </exception>
		/// <exception cref="System.ArgumentException">
		/// <para>The <paramref name="host"/> is a zero-length string.</para>
		/// <para>-or-</para>
		/// <para>The length of <paramref name="host"/> is greater than 255 characters.</para>
		/// </exception>
		protected ProxyClient (string host, int port)
		{
			if (host == null)
				throw new ArgumentNullException (nameof (host));

			if (host.Length == 0 || host.Length > 255)
				throw new ArgumentException ("The length of the host name must be between 0 and 256 characters.", nameof (host));

			if (port < 0 || port > 65535)
				throw new ArgumentOutOfRangeException (nameof (port));

			ProxyHost = host;
			ProxyPort = port == 0 ? 1080 : port;
		}

		/// <summary>
		/// Initializes a new instance of the <see cref="T:MailKit.Net.Proxy.ProxyClient"/> class.
		/// </summary>
		/// <remarks>
		/// Initializes a new instance of the <see cref="T:MailKit.Net.Proxy.ProxyClient"/> class.
		/// </remarks>
		/// <param name="host">The host name of the proxy server.</param>
		/// <param name="port">The proxy server port.</param>
		/// <param name="credentials">The credentials to use to authenticate with the proxy server.</param>
		/// <exception cref="System.ArgumentNullException">

View on GitHub (pinned to 9d3859a785)