jstedfast/MailKit · error · NotSupportedException

The IMAP server does not support the PARTIAL extension.

Error message

The IMAP server does not support the PARTIAL extension.

What it means

CheckCanFetch(IList<UniqueId>, IFetchRequest) throws this NotSupportedException when request.PartialRange is set but the server's capabilities do not include ImapCapabilities.Partial. The PARTIAL fetch modifier (RFC 9051 / partial extensions) lets a fetch return only a byte/item range; MailKit refuses to build the command when the server cannot honor it.

Solutions

1. Check client.Capabilities for ImapCapabilities.Partial before setting request.PartialRange
2. Remove PartialRange and fetch the full item instead
3. Emulate partial retrieval with BODY[]<start.length> section specifiers if the server supports them

Example fix

// before
request.PartialRange = new PartialRange(0, 10240);
var summaries = folder.Fetch(uids, request);
// after
if ((client.Capabilities & ImapCapabilities.Partial) != 0) {
    request.PartialRange = new PartialRange(0, 10240);
} else {
    request.PartialRange = null; // full fetch
}
var summaries = folder.Fetch(uids, request);

if (request.PartialRange.HasValue && (client.Capabilities & ImapCapabilities.Partial) == 0)
    request.PartialRange = null; // fetch full items instead
var summaries = folder.Fetch(uids, request);

try {
    summaries = folder.Fetch(uids, request);
} catch (NotSupportedException) {
    request.PartialRange = null;
    summaries = folder.Fetch(uids, request);
}

When it happens

Trigger: Calling Fetch(IList<UniqueId> uids, IFetchRequest request) or FetchAsync with request.PartialRange.HasValue on an IMAP server that does not advertise the PARTIAL capability.

Common situations: Using partial fetch to resume large BODY[] downloads or limit bandwith, aimed at a server without PARTIAL support; code written against newer servers (RFC 9051 IMAP4rev2) being run against older rev1 servers.

Related errors

• The set of unique identifiers is too large to fetch with a…
• The PARTIAL extension only supports UID-based FETCH…
• The ImapFolder does not support mod-sequences.
• The IMAP server does not support the METADATA extension.
• The IMAP server does not support the QUOTA extension.

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

Appendix: source

Thrown at MailKit/Net/Imap/ImapFolderFetch.cs:1099

		internal static bool IsEmptyFetchRequest (IFetchRequest request)
		{
			return request.Items == MessageSummaryItems.None && (request.Headers == null || (request.Headers.Count == 0 && !request.Headers.Exclude));
		}

		bool CheckCanFetch (IList<UniqueId> uids, IFetchRequest request)
		{
			if (uids == null)
				throw new ArgumentNullException (nameof (uids));

			if (request == null)
				throw new ArgumentNullException (nameof (request));

			if (request.ChangedSince.HasValue && !supportsModSeq)
				throw new NotSupportedException ("The ImapFolder does not support mod-sequences.");

			if (request.PartialRange.HasValue && (Engine.Capabilities & ImapCapabilities.Partial) == 0)
				throw new NotSupportedException ("The IMAP server does not support the PARTIAL extension.");

			CheckState (true, false);

			return uids.Count > 0 && !IsEmptyFetchRequest (request);
		}

		string CreateFetchCommand (IList<UniqueId> uids, IFetchRequest request, out bool previewText)
		{
			var query = FormatSummaryItems (Engine, request, out previewText);
			var command = new StringBuilder ("UID FETCH %s ");

			command.Append (query);

			if (request.ChangedSince.HasValue || request.PartialRange.HasValue) {
				command.Append (" (");

				if (request.ChangedSince.HasValue) {
					command.AppendFormat (CultureInfo.InvariantCulture, "CHANGEDSINCE {0}", request.ChangedSince.Value);

View on GitHub (pinned to 9d3859a785)