{"record":{"id":"58977bde63c102e0","repo":"jstedfast/MailKit","slug":"the-pop3-server-has-unexpectedly-disconnected","errorCode":null,"errorMessage":"The POP3 server has unexpectedly disconnected.","messagePattern":"The POP3 server has unexpectedly disconnected\\.","errorType":"exception","errorClass":"Pop3ProtocolException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Pop3/Pop3Stream.cs","lineNumber":307,"sourceCode":"\t\t\t\t}\n\n\t\t\t\tinputIndex = index;\n\t\t\t\tinputEnd = start;\n\t\t\t} else {\n\t\t\t\tinputIndex = start;\n\t\t\t\tinputEnd = start;\n\t\t\t}\n\n\t\t\tend = input.Length - PadSize;\n\t\t}\n\n\t\tvoid OnReadAhead (int start, int nread)\n\t\t{\n\t\t\tif (nread > 0) {\n\t\t\t\tlogger.LogServer (input, start, nread);\n\t\t\t\tinputEnd += nread;\n\t\t\t} else {\n\t\t\t\tthrow new Pop3ProtocolException (\"The POP3 server has unexpectedly disconnected.\");\n\t\t\t}\n\t\t}\n\n\t\tint ReadAhead (CancellationToken cancellationToken)\n\t\t{\n\t\t\tAlignReadAheadBuffer (out int start, out int end);\n\n\t\t\ttry {\n\t\t\t\tvar network = Stream as NetworkStream;\n\t\t\t\tint nread;\n\n\t\t\t\tcancellationToken.ThrowIfCancellationRequested ();\n\n\t\t\t\tnetwork?.Poll (SelectMode.SelectRead, cancellationToken);\n\t\t\t\tnread = Stream.Read (input, start, end - start);\n\n\t\t\t\tOnReadAhead (start, nread);\n\t\t\t} catch {","sourceCodeStart":289,"sourceCodeEnd":325,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Pop3/Pop3Stream.cs#L289-L325","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Wrap the whole session in try/catch for Pop3ProtocolException/ServiceNotConnectedException and reconnect, re-authenticate, and resume.","Avoid long idle periods: keep-alive with NOOP or close/reopen the client between batches.","Enable TLS and check for middleboxes (NAT, firewalls) with aggressive idle timeouts.","Track processed UIDs so the work can resume from the last completed message after reconnect.","Retry with exponential backoff; treat the connection as poisoned — do not reuse the client instance."],"exampleFix":"// before\nclient.DownloadMessages(allIndexes); // one drop kills the whole run\n// after\ntry {\n    client.DownloadMessages(allIndexes);\n} catch (Pop3ProtocolException) {\n    client.Dispose();\n    client = ReconnectAndAuthenticate(); // then resume from last successful UID\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    Work(client);\n} catch (Pop3ProtocolException ex) when (ex.Message.Contains(\"unexpectedly disconnected\")) {\n    client.Dispose();\n    await Task.Delay(backoff);\n    client = CreateAndAuthenticateClient(); // then resume from last UID\n}","preventionTips":["Send a NOOP periodically to survive server idle timeouts","Checkpoint progress by UID so reconnects can resume mid-batch","Always build fresh client instances after a disconnect — never reuse the dead one","Avoid huge single commands on flaky networks; fetch in bounded batches"],"tags":["pop3","network","disconnection","timeout","mailkit"],"backgroundTag":"broken-pipe","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"}