jstedfast/MailKit · error · IOException

Failed to resolve host

Error message

Failed to resolve host: {0}

What it means

SocketUtils.Connect resolves the host via DNS and tries each returned IP address; if resolution returns no usable addresses (or all connect attempts were skipped because the list was empty), it throws IOException("Failed to resolve host: <host>"). Note this is the empty-resolution path — a thrown DNS exception is rethrown instead.

Solutions

1. Verify the hostname with nslookup/dig from the same environment
2. Fix DNS configuration (resolver addresses, /etc/resolv.conf, VPN or corporate DNS)
3. Use an IP address directly (with certificate validation implications) or correct the hostname in config
4. Add network connectivity/DNS checks before connecting and handle IOException with a clear message

Example fix

// before
client.Connect("smtp.exampl.com", 587); // typo -> IOException: Failed to resolve host
// after
client.Connect("smtp.example.com", 587);

// validate before connecting
var host = new Uri(smtpUri).Host;
var addresses = await Dns.GetHostAddressesAsync(host);
if (addresses.Length == 0) throw new ArgumentException($"Cannot resolve {host}");

try
{
    client.Connect(host, port, SecureSocketOptions.Auto);
}
catch (IOException ex) when (ex.Message.StartsWith("Failed to resolve host"))
{
    logger.LogError("DNS failure for {Host}: {Message}", host, ex.Message);
}

When it happens

Trigger: Calling SmtpClient/Pop3/Imap Connect (sync path) with a hostname that DNS cannot resolve to any address, so ipAddresses.Length == 0.

Common situations: Typo in hostname; DNS outage or misconfigured resolver (e.g. in containers/Docker networks); host removed from DNS; corporate DNS blocking external lookups; offline machine.

Related errors

• The SMTP server has unexpectedly disconnected
• The SMTP server has unexpectedly disconnected.
• Specified argument was out of the range of valid values…
• Value cannot be null. (Parameter 'message')
• Value cannot be null. (Parameter 'response')

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

Appendix: source

Thrown at MailKit/Net/SocketUtils.cs:171

					return socket;
				} catch (OperationCanceledException) {
					throw;
				} catch (Exception ex) {
					if (!cancellationToken.CanBeCanceled) {
#if NET6_0_OR_GREATER
						Telemetry.Socket.Metrics?.RecordConnectFailed (connectStartTicks, ipAddresses[i], host, port, false, ex);
#endif

						socket.Dispose ();
					}

					if (i + 1 == ipAddresses.Length)
						throw;
				}
			}

			throw new IOException (string.Format ("Failed to resolve host: {0}", host));
		}

		public static async Task<Socket> ConnectAsync (string host, int port, IPEndPoint? localEndPoint, CancellationToken cancellationToken)
		{
			cancellationToken.ThrowIfCancellationRequested ();

#if NET6_0_OR_GREATER
			var ipAddresses = await Dns.GetHostAddressesAsync (host, cancellationToken).ConfigureAwait (false);
#else
			var ipAddresses = await Dns.GetHostAddressesAsync (host).ConfigureAwait (false);
#endif

			for (int i = 0; i < ipAddresses.Length; i++) {
				cancellationToken.ThrowIfCancellationRequested ();

				var socket = new Socket (ipAddresses[i].AddressFamily, SocketType.Stream, ProtocolType.Tcp);

				try {

View on GitHub (pinned to 9d3859a785)