jstedfast/MailKit · error · ArgumentException

The uri must be absolute.

Error message

The uri must be absolute.

What it means

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.

Solutions

1. Prefix the URI with the correct scheme, e.g. new Uri("smtps://mail.example.com:465") or "smtp://host:587"
2. Instead pass the host string and port to the Connect(string host, int port, ...) overload
3. Validate uri.IsAbsoluteUri before calling Connect

Example fix

// before
var uri = new Uri("mail.example.com:587");
client.Connect(uri);
// after
var uri = new Uri("smtp://mail.example.com:587");
client.Connect(uri);

if (uri == null || !uri.IsAbsoluteUri)
    throw new ArgumentException("SMTP URI must be absolute, e.g. smtp://host:587", nameof(uri));
client.Connect(uri);

static bool IsAbsoluteMailUri(Uri uri) => uri != null && uri.IsAbsoluteUri;

try { client.Connect(uri); }
catch (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); }

When it happens

Trigger: Calling MailService.Connect(Uri) with a relative URI, e.g. new Uri("mail.example.com") or new Uri("/mail"), which lacks a scheme.

Common situations: 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.

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

• Unknown URI scheme.
• 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/521517b5936e2f8c. Report an issue: GitHub.

Appendix: source

Thrown at MailKit/MailService.cs:848

		/// <exception cref="System.OperationCanceledException">
		/// The operation was canceled via the cancellation token.
		/// </exception>
		/// <exception cref="System.Net.Sockets.SocketException">
		/// A socket error occurred trying to connect to the remote host.
		/// </exception>
		/// <exception cref="System.IO.IOException">
		/// An I/O error occurred.
		/// </exception>
		/// <exception cref="ProtocolException">
		/// A protocol error occurred.
		/// </exception>
		public void Connect (Uri uri, CancellationToken cancellationToken = default)
		{
			if (uri == null)
				throw new ArgumentNullException (nameof (uri));

			if (!uri.IsAbsoluteUri)
				throw new ArgumentException ("The uri must be absolute.", nameof (uri));

			var options = GetSecureSocketOptions (uri);

			Connect (uri.Host, uri.Port < 0 ? 0 : uri.Port, options, cancellationToken);
		}

		/// <summary>
		/// Asynchronously establish a connection to the specified mail server.
		/// </summary>
		/// <remarks>
		/// Asynchronously establishes a connection to the specified mail server.
		/// </remarks>
		/// <returns>An asynchronous task context.</returns>
		/// <param name="uri">The server URI.</param>
		/// <param name="cancellationToken">The cancellation token.</param>
		/// <exception cref="System.ArgumentNullException">
		/// The <paramref name="uri"/> is <see langword="null" />.
		/// </exception>

View on GitHub (pinned to 9d3859a785)