{"record":{"id":"521517b5936e2f8c","repo":"jstedfast/MailKit","slug":"the-uri-must-be-absolute","errorCode":null,"errorMessage":"The uri must be absolute.","messagePattern":"The uri must be absolute\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"MailKit/MailService.cs","lineNumber":848,"sourceCode":"\t\t/// <exception cref=\"System.OperationCanceledException\">\n\t\t/// The operation was canceled via the cancellation token.\n\t\t/// </exception>\n\t\t/// <exception cref=\"System.Net.Sockets.SocketException\">\n\t\t/// A socket error occurred trying to connect to the remote host.\n\t\t/// </exception>\n\t\t/// <exception cref=\"System.IO.IOException\">\n\t\t/// An I/O error occurred.\n\t\t/// </exception>\n\t\t/// <exception cref=\"ProtocolException\">\n\t\t/// A protocol error occurred.\n\t\t/// </exception>\n\t\tpublic void Connect (Uri uri, CancellationToken cancellationToken = default)\n\t\t{\n\t\t\tif (uri == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (uri));\n\n\t\t\tif (!uri.IsAbsoluteUri)\n\t\t\t\tthrow new ArgumentException (\"The uri must be absolute.\", nameof (uri));\n\n\t\t\tvar options = GetSecureSocketOptions (uri);\n\n\t\t\tConnect (uri.Host, uri.Port < 0 ? 0 : uri.Port, options, cancellationToken);\n\t\t}\n\n\t\t/// <summary>\n\t\t/// Asynchronously establish a connection to the specified mail server.\n\t\t/// </summary>\n\t\t/// <remarks>\n\t\t/// Asynchronously establishes a connection to the specified mail server.\n\t\t/// </remarks>\n\t\t/// <returns>An asynchronous task context.</returns>\n\t\t/// <param name=\"uri\">The server URI.</param>\n\t\t/// <param name=\"cancellationToken\">The cancellation token.</param>\n\t\t/// <exception cref=\"System.ArgumentNullException\">\n\t\t/// The <paramref name=\"uri\"/> is <see langword=\"null\" />.\n\t\t/// </exception>","sourceCodeStart":830,"sourceCodeEnd":866,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/MailService.cs#L830-L866","documentation":"MailKit's Connect(Uri) overload requires a fully-qualified absolute URI because it extracts the host, port, and SecureSocketOptions from it. A relative URI (no scheme such as smtp:// or imaps://) has no host, so the library throws ArgumentException immediately to fail fast.","triggerScenarios":"Calling MailService.Connect(Uri) with a relative URI, e.g. new Uri(\"mail.example.com\") or new Uri(\"/mail\"), which lacks a scheme.","commonSituations":"Building a URI from a config value that forgot the scheme prefix (e.g. reading 'smtp.example.com:587' from appsettings and wrapping it in Uri), or users confusing MailKit's Uri overload with the string host overload.","solutions":["Prefix the URI with the correct scheme, e.g. new Uri(\"smtps://mail.example.com:465\") or \"smtp://host:587\"","Instead pass the host string and port to the Connect(string host, int port, ...) overload","Validate uri.IsAbsoluteUri before calling Connect"],"exampleFix":"// before\nvar uri = new Uri(\"mail.example.com:587\");\nclient.Connect(uri);\n// after\nvar uri = new Uri(\"smtp://mail.example.com:587\");\nclient.Connect(uri);","handlingStrategy":"validation","validationCode":"if (uri == null || !uri.IsAbsoluteUri)\n    throw new ArgumentException(\"SMTP URI must be absolute, e.g. smtp://host:587\", nameof(uri));\nclient.Connect(uri);","typeGuard":"static bool IsAbsoluteMailUri(Uri uri) => uri != null && uri.IsAbsoluteUri;","tryCatchPattern":"try { client.Connect(uri); }\ncatch (ArgumentException ex) when (ex.Message.Contains(\"uri must be absolute\")) { log.LogError(\"Mail URI must include a scheme: {Uri}\", uri); throw new ConfigurationException(\"Mail server URI must be absolute\", ex); }","preventionTips":["Always include a scheme (smtp://, smtps://, imap://, imaps://) when building mail URIs from config","Prefer the Connect(host, port, options) overload when you have separate host/port values","Add a startup validation step that asserts all configured mail URIs are absolute"],"tags":["mailkit","argumentexception","uri","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-16T04:17:20.429Z"}