jstedfast/MailKit · error · Pop3ProtocolException

The POP3 server has unexpectedly disconnected.

Error message

The POP3 server has unexpectedly disconnected.

What it means

Pop3Stream performs read-ahead buffering; OnReadAhead is invoked when the async read completes. If the read returns 0 or negative bytes, the server closed or reset the connection, so Pop3Stream throws Pop3ProtocolException('The POP3 server has unexpectedly disconnected.'). This surfaces while waiting for a command response, not on the network call itself.

Solutions

1. Wrap the whole session in try/catch for Pop3ProtocolException/ServiceNotConnectedException and reconnect, re-authenticate, and resume.
2. Avoid long idle periods: keep-alive with NOOP or close/reopen the client between batches.
3. Enable TLS and check for middleboxes (NAT, firewalls) with aggressive idle timeouts.
4. Track processed UIDs so the work can resume from the last completed message after reconnect.
5. Retry with exponential backoff; treat the connection as poisoned — do not reuse the client instance.

Example fix

// before
client.DownloadMessages(allIndexes); // one drop kills the whole run
// after
try {
    client.DownloadMessages(allIndexes);
} catch (Pop3ProtocolException) {
    client.Dispose();
    client = ReconnectAndAuthenticate(); // then resume from last successful UID
}

try {
    Work(client);
} catch (Pop3ProtocolException ex) when (ex.Message.Contains("unexpectedly disconnected")) {
    client.Dispose();
    await Task.Delay(backoff);
    client = CreateAndAuthenticateClient(); // then resume from last UID
}

When it happens

Trigger: Any command in progress (LIST, RETR, etc.) when the POP3 server drops the connection: server-side idle timeout, network interruption, load balancer closing idle sockets, or server crash while streaming a large message body.

Common situations: Long-running download over an unreliable network or mobile connection; provider enforces a short idle timeout between commands (e.g. 60s); NAT/firewall silently dropping the TCP session; server restarted mid-session.

Related errors

• Operation timed out after
• Operation timed out after
• Unexpected response from server
• The SMTP server has unexpectedly disconnected
• The SMTP server has unexpectedly disconnected.

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

Appendix: source

Thrown at MailKit/Net/Pop3/Pop3Stream.cs:307

				}

				inputIndex = index;
				inputEnd = start;
			} else {
				inputIndex = start;
				inputEnd = start;
			}

			end = input.Length - PadSize;
		}

		void OnReadAhead (int start, int nread)
		{
			if (nread > 0) {
				logger.LogServer (input, start, nread);
				inputEnd += nread;
			} else {
				throw new Pop3ProtocolException ("The POP3 server has unexpectedly disconnected.");
			}
		}

		int ReadAhead (CancellationToken cancellationToken)
		{
			AlignReadAheadBuffer (out int start, out int end);

			try {
				var network = Stream as NetworkStream;
				int nread;

				cancellationToken.ThrowIfCancellationRequested ();

				network?.Poll (SelectMode.SelectRead, cancellationToken);
				nread = Stream.Read (input, start, end - start);

				OnReadAhead (start, nread);
			} catch {

View on GitHub (pinned to 9d3859a785)