jstedfast/MailKit · error · ArgumentException

Unknown URI scheme.

Error message

Unknown URI scheme.

What it means

MailService.GetSecureSocketOptions parses the scheme of a URI (used by MailService.Connect(uri) style APIs) and maps protocols like 'imaps'/'pop3s' to SslOnConnect and the plain protocol (optionally with a starttls query parameter) to the appropriate option. When the URI scheme matches neither the protocol nor its 's' variant (e.g. 'http://' or 'smtp2://' passed to an ImapClient), it throws ArgumentException('Unknown URI scheme.', nameof(uri)).

Solutions

1. Match the URI scheme to the client protocol: use imaps://imap.example.com with ImapClient, pop3s:// with Pop3Client, smtps:// with SmtpClient.
2. Use the correct client class for the scheme, or drop the scheme and call Connect(host, port, SecureSocketOptions, ...) directly.
3. Verify the scheme spelling and that no proxy/override scheme (http, https) leaked into the mail URI.

Example fix

// before (ImapClient)
client.Connect(new Uri("https://imap.example.com"));
// after
client.Connect(new Uri("imaps://imap.example.com"));

var allowed = new[] { "imap", "imaps" }; // per client type
if (uri == null || !allowed.Contains(uri.Scheme, StringComparer.OrdinalIgnoreCase))
    throw new ArgumentException($"Expected {string.Join("/", allowed)} scheme, got {uri?.Scheme}", nameof(uri));

static bool IsMailUri(Uri uri, string protocol) =>
    uri != null && (uri.Scheme.Equals(protocol, StringComparison.OrdinalIgnoreCase) ||
                    uri.Scheme.Equals(protocol + "s", StringComparison.OrdinalIgnoreCase));

try {
    client.Connect(uri);
} catch (ArgumentException ex) when (ex.ParamName == "uri") {
    logger.LogError("Unsupported URI scheme {Scheme}", uri.Scheme);
    throw;
}

When it happens

Trigger: Calling Connect/other APIs that accept a Uri where uri.Scheme is not the service protocol (imap/imaps for ImapClient, pop3/pop3s for Pop3Client, smtp/smtps for SmtpClient), case-insensitively.

Common situations: Using the wrong client type for the URI (e.g. SmtpClient with an imaps:// URI), typos in the scheme (imap:// vs imail://), or generic http/https URLs pasted into mail client configuration.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• The uri must be absolute.
• The host name cannot be empty.
• The Pop3Client must be connected before you can…
• Unexpected greeting from server
• Failed to connect to

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

Appendix: source

Thrown at MailKit/MailService.cs:792

			return false;
		}

		internal SecureSocketOptions GetSecureSocketOptions (Uri uri)
		{
			var query = uri.ParsedQuery ();
			var protocol = uri.Scheme;

			// Note: early versions of MailKit used "pop3" and "pop3s"
			if (protocol.Equals ("pop3s", StringComparison.OrdinalIgnoreCase))
				protocol = "pops";
			else if (protocol.Equals ("pop3", StringComparison.OrdinalIgnoreCase))
				protocol = "pop";

			if (protocol.Equals (Protocol + "s", StringComparison.OrdinalIgnoreCase))
				return SecureSocketOptions.SslOnConnect;

			if (!protocol.Equals (Protocol, StringComparison.OrdinalIgnoreCase))
				throw new ArgumentException ("Unknown URI scheme.", nameof (uri));

			if (query.TryGetValue ("starttls", out string? value)) {
				if (IsAny (value, "always", "true", "yes"))
					return SecureSocketOptions.StartTls;

				if (IsAny (value, "never", "false", "no"))
					return SecureSocketOptions.None;

				return SecureSocketOptions.StartTlsWhenAvailable;
			}

			return SecureSocketOptions.StartTlsWhenAvailable;
		}

		/// <summary>
		/// Establish a connection to the specified mail server.
		/// </summary>
		/// <remarks>

View on GitHub (pinned to 9d3859a785)