jstedfast/MailKit · error · NotSupportedException

The POP3 server does not support the UIDL extension.

Error message

The POP3 server does not support the UIDL extension.

What it means

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.

Solutions

1. Avoid per-message GetUid; if the server lacks UIDL, MailKit cannot provide stable UIDs - use message sequence numbers instead.
2. Catch NotSupportedException and fall back to index-based message handling.
3. Use a server/mailbox that supports UIDL, or add a local cache keyed by message headers instead of UIDs.
4. Check SupportsUids (or capabilities) before issuing GetUid calls.

Example fix

// before
string uid = client.GetUid (index, cancellationToken);
// after
string uid = client.SupportsUids
    ? client.GetUid (index, cancellationToken)
    : null; // fall back to sequence-number-based handling

if (!client.SupportsUids)
    return null; // UIDL probed and absent; use sequence numbers

try {
    string uid = client.GetUid (index, cancellationToken);
} catch (NotSupportedException) {
    // fall back to index-based message access
}

When it happens

Trigger: 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).

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

Related errors

• The POP3 server does not support the UTF8 extension.
• The POP3 server does not support the LANG extension.
• The IMAP server does not support the QRESYNC extension.
• The IMAP server does not support the UTF8=ACCEPT extension.
• The IMAP server does not support the ID extension.

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

Appendix: source

Thrown at MailKit/Net/Pop3/Pop3Client.cs:1880

				return Task.CompletedTask;
			}

			pc.UserData = tokens[1];

			return Task.CompletedTask;
		}

		Pop3Command QueueUidlCommand (int index)
		{
			CheckDisposed ();
			CheckConnected ();
			CheckAuthenticated ();

			if (index < 0 || index >= total)
				throw new ArgumentOutOfRangeException (nameof (index));

			if (!SupportsUids && (probed & ProbedCapabilities.UIDL) != 0)
				throw new NotSupportedException ("The POP3 server does not support the UIDL extension.");

			return engine.QueueCommand (ProcessUidlResponse, "UIDL {0}\r\n", index + 1);
		}

		T OnUidlComplete<T> (Pop3Command pc)
		{
			probed |= ProbedCapabilities.UIDL;

			if (pc.Status != Pop3CommandStatus.Ok && !SupportsUids)
				throw new NotSupportedException ("The POP3 server does not support the UIDL extension.");

			pc.ThrowIfError ();

			engine.Capabilities |= Pop3Capabilities.UIDL;

			return (T) pc.UserData!;
		}

View on GitHub (pinned to 9d3859a785)