{"record":{"id":"97762c6e609060ad","repo":"jstedfast/MailKit","slug":"unknown-uri-scheme","errorCode":null,"errorMessage":"Unknown URI scheme.","messagePattern":"Unknown URI scheme\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"MailKit/MailService.cs","lineNumber":792,"sourceCode":"\t\t\treturn false;\n\t\t}\n\n\t\tinternal SecureSocketOptions GetSecureSocketOptions (Uri uri)\n\t\t{\n\t\t\tvar query = uri.ParsedQuery ();\n\t\t\tvar protocol = uri.Scheme;\n\n\t\t\t// Note: early versions of MailKit used \"pop3\" and \"pop3s\"\n\t\t\tif (protocol.Equals (\"pop3s\", StringComparison.OrdinalIgnoreCase))\n\t\t\t\tprotocol = \"pops\";\n\t\t\telse if (protocol.Equals (\"pop3\", StringComparison.OrdinalIgnoreCase))\n\t\t\t\tprotocol = \"pop\";\n\n\t\t\tif (protocol.Equals (Protocol + \"s\", StringComparison.OrdinalIgnoreCase))\n\t\t\t\treturn SecureSocketOptions.SslOnConnect;\n\n\t\t\tif (!protocol.Equals (Protocol, StringComparison.OrdinalIgnoreCase))\n\t\t\t\tthrow new ArgumentException (\"Unknown URI scheme.\", nameof (uri));\n\n\t\t\tif (query.TryGetValue (\"starttls\", out string? value)) {\n\t\t\t\tif (IsAny (value, \"always\", \"true\", \"yes\"))\n\t\t\t\t\treturn SecureSocketOptions.StartTls;\n\n\t\t\t\tif (IsAny (value, \"never\", \"false\", \"no\"))\n\t\t\t\t\treturn SecureSocketOptions.None;\n\n\t\t\t\treturn SecureSocketOptions.StartTlsWhenAvailable;\n\t\t\t}\n\n\t\t\treturn SecureSocketOptions.StartTlsWhenAvailable;\n\t\t}\n\n\t\t/// <summary>\n\t\t/// Establish a connection to the specified mail server.\n\t\t/// </summary>\n\t\t/// <remarks>","sourceCodeStart":774,"sourceCodeEnd":810,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/MailService.cs#L774-L810","documentation":"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)).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Match the URI scheme to the client protocol: use imaps://imap.example.com with ImapClient, pop3s:// with Pop3Client, smtps:// with SmtpClient.","Use the correct client class for the scheme, or drop the scheme and call Connect(host, port, SecureSocketOptions, ...) directly.","Verify the scheme spelling and that no proxy/override scheme (http, https) leaked into the mail URI."],"exampleFix":"// before (ImapClient)\nclient.Connect(new Uri(\"https://imap.example.com\"));\n// after\nclient.Connect(new Uri(\"imaps://imap.example.com\"));","handlingStrategy":"validation","validationCode":"var allowed = new[] { \"imap\", \"imaps\" }; // per client type\nif (uri == null || !allowed.Contains(uri.Scheme, StringComparer.OrdinalIgnoreCase))\n    throw new ArgumentException($\"Expected {string.Join(\"/\", allowed)} scheme, got {uri?.Scheme}\", nameof(uri));","typeGuard":"static bool IsMailUri(Uri uri, string protocol) =>\n    uri != null && (uri.Scheme.Equals(protocol, StringComparison.OrdinalIgnoreCase) ||\n                    uri.Scheme.Equals(protocol + \"s\", StringComparison.OrdinalIgnoreCase));","tryCatchPattern":"try {\n    client.Connect(uri);\n} catch (ArgumentException ex) when (ex.ParamName == \"uri\") {\n    logger.LogError(\"Unsupported URI scheme {Scheme}\", uri.Scheme);\n    throw;\n}","preventionTips":["Match the URI scheme to the client protocol (imaps for ImapClient, pop3s for Pop3Client, smtps for SmtpClient)","Validate schemes from user/config input before constructing the client call","Prefer explicit Connect(host, port, SecureSocketOptions) over URI-based connect when the scheme is untrusted"],"tags":["mailkit","uri","scheme","connection"],"backgroundTag":"invalid-url-format","analyzedSha":"9d3859a7855e3e17582c07fd01972b8e262bf176","analyzedAt":"2026-09-15T15:46:11.592Z","contentChangedAt":"2026-09-15T15:46:11.592Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}