{"record":{"id":"41ddd05a88646feb","repo":"jstedfast/MailKit","slug":"the-pop3-server-does-not-support-the-uidl-extension","errorCode":null,"errorMessage":"The POP3 server does not support the UIDL extension.","messagePattern":"The POP3 server does not support the UIDL extension\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Pop3/Pop3Client.cs","lineNumber":1880,"sourceCode":"\t\t\t\treturn Task.CompletedTask;\n\t\t\t}\n\n\t\t\tpc.UserData = tokens[1];\n\n\t\t\treturn Task.CompletedTask;\n\t\t}\n\n\t\tPop3Command QueueUidlCommand (int index)\n\t\t{\n\t\t\tCheckDisposed ();\n\t\t\tCheckConnected ();\n\t\t\tCheckAuthenticated ();\n\n\t\t\tif (index < 0 || index >= total)\n\t\t\t\tthrow new ArgumentOutOfRangeException (nameof (index));\n\n\t\t\tif (!SupportsUids && (probed & ProbedCapabilities.UIDL) != 0)\n\t\t\t\tthrow new NotSupportedException (\"The POP3 server does not support the UIDL extension.\");\n\n\t\t\treturn engine.QueueCommand (ProcessUidlResponse, \"UIDL {0}\\r\\n\", index + 1);\n\t\t}\n\n\t\tT OnUidlComplete<T> (Pop3Command pc)\n\t\t{\n\t\t\tprobed |= ProbedCapabilities.UIDL;\n\n\t\t\tif (pc.Status != Pop3CommandStatus.Ok && !SupportsUids)\n\t\t\t\tthrow new NotSupportedException (\"The POP3 server does not support the UIDL extension.\");\n\n\t\t\tpc.ThrowIfError ();\n\n\t\t\tengine.Capabilities |= Pop3Capabilities.UIDL;\n\n\t\t\treturn (T) pc.UserData!;\n\t\t}\n","sourceCodeStart":1862,"sourceCodeEnd":1898,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Pop3/Pop3Client.cs#L1862-L1898","documentation":"Pop3Client's per-message GetUid (GetUid variant) throws this NotSupportedException when UIDL support has already been probed and found absent (SupportsUids is false and the ProbedCapabilities.UIDL flag is set). MailKit caches the result of a UIDL probe; once the server is known not to support UIDL, later UID requests fail fast instead of re-sending the doomed command.","triggerScenarios":"Calling GetUid(index) after an earlier UIDL attempt revealed the server lacks UIDL support; fetching message UIDs individually on a server without the UIDL extension (RFC 1939 optional feature).","commonSituations":"Legacy POP3 servers (some Exchange/old qmail setups) without UIDL; code iterating messages and calling GetUid per message after the capability was probed once; POP3 servers where the first UIDL returned -ERR.","solutions":["Avoid per-message GetUid; if the server lacks UIDL, MailKit cannot provide stable UIDs - use message sequence numbers instead.","Catch NotSupportedException and fall back to index-based message handling.","Use a server/mailbox that supports UIDL, or add a local cache keyed by message headers instead of UIDs.","Check SupportsUids (or capabilities) before issuing GetUid calls."],"exampleFix":"// before\nstring uid = client.GetUid (index, cancellationToken);\n// after\nstring uid = client.SupportsUids\n    ? client.GetUid (index, cancellationToken)\n    : null; // fall back to sequence-number-based handling","handlingStrategy":"validation","validationCode":"if (!client.SupportsUids)\n    return null; // UIDL probed and absent; use sequence numbers","typeGuard":null,"tryCatchPattern":"try {\n    string uid = client.GetUid (index, cancellationToken);\n} catch (NotSupportedException) {\n    // fall back to index-based message access\n}","preventionTips":["Check SupportsUids once per session before any UID API","Design message handling to work by sequence number when UIDs are unavailable","Prefer IMAP when stable unique identifiers are a requirement"],"tags":["pop3","uidl","uid","capability","mailkit"],"backgroundTag":"feature-not-enabled","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"}