{"record":{"id":"8c6bcc56de74510e","repo":"jstedfast/MailKit","slug":"the-imap-server-does-not-support-the-partial-extension-8c6bcc","errorCode":null,"errorMessage":"The IMAP server does not support the PARTIAL extension.","messagePattern":"The IMAP server does not support the PARTIAL extension\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolderSearch.cs","lineNumber":1052,"sourceCode":"\t\t\treturn ProcessSearchResponse (ic);\n\t\t}\n\n\t\tImapCommand QueueSearchCommand (SearchOptions options, SearchQuery query, PartialRange? partialRange, CancellationToken cancellationToken, out string? charset)\n\t\t{\n\t\t\tif (query == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (query));\n\n\t\t\tCheckState (true, false);\n\n\t\t\tif (options != SearchOptions.None && (Engine.Capabilities & ImapCapabilities.ESearch) == 0)\n\t\t\t\tthrow new NotSupportedException (\"The IMAP server does not support the ESEARCH extension.\");\n\n\t\t\tif (partialRange.HasValue) {\n\t\t\t\t// Note: RFC 9394 advertises the \"PARTIAL\" capability while RFC 5267 defines the same PARTIAL\n\t\t\t\t// search return option under the \"CONTEXT=SEARCH\" capability.\n\t\t\t\tif ((Engine.Capabilities & ImapCapabilities.Partial) == 0 &&\n\t\t\t\t\t((Engine.Capabilities & ImapCapabilities.Context) == 0 || !Engine.SupportedContexts.Contains (\"SEARCH\")))\n\t\t\t\t\tthrow new NotSupportedException (\"The IMAP server does not support the PARTIAL extension.\");\n\n\t\t\t\t// Note: Negative partial ranges were introduced in RFC 9394 and are not defined by RFC 5267.\n\t\t\t\tif (partialRange.Value.First < 0 && (Engine.Capabilities & ImapCapabilities.Partial) == 0)\n\t\t\t\t\tthrow new NotSupportedException (\"The IMAP server does not support negative partial ranges.\");\n\t\t\t}\n\n\t\t\tvar args = new List<object> ();\n\t\t\tvar optimized = query.Optimize (new ImapSearchQueryOptimizer ());\n\t\t\tvar expr = BuildQueryExpression (optimized, args, out charset);\n\t\t\tvar command = new StringBuilder (\"UID SEARCH \");\n\n\t\t\tif ((Engine.Capabilities & ImapCapabilities.ESearch) != 0 || partialRange.HasValue) {\n\t\t\t\tcommand.Append (\"RETURN (\");\n\n\t\t\t\tif (options != SearchOptions.All && options != SearchOptions.None) {\n\t\t\t\t\tif ((options & SearchOptions.All) != 0)\n\t\t\t\t\t\tcommand.Append (\"ALL \");\n\t\t\t\t\tif ((options & SearchOptions.Relevancy) != 0)","sourceCodeStart":1034,"sourceCodeEnd":1070,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolderSearch.cs#L1034-L1070","documentation":"MailKit throws this NotSupportedException when a Search call supplies a PartialRange but the server neither advertises the PARTIAL capability (RFC 9394) nor CONTEXT=SEARCH with the SEARCH context (RFC 5267), the two specs that define partial search-result returns. The library refuses to send a partial range the server would reject or, worse, misinterpret.","triggerScenarios":"Calling folder.Search(SearchOptions.None, query, new PartialRange(0, 10)) or its async variant on a server lacking both ImapCapabilities.Partial and (Context + SupportedContexts containing \"SEARCH\").","commonSituations":"Paging through search results against older servers that predate RFC 9394 and don't implement CONTEXT=SEARCH; assuming the PARTIAL option is universally available; self-hosted IMAP servers with limited capability sets.","solutions":["Check client.Capabilities for ImapCapabilities.Partial (or Context with \"SEARCH\") before constructing a PartialRange.","Fetch all matching UIDs with a plain Search and slice/paginate the result list in your application instead.","Use folder.Fetch with ranges over the returned IDs to emulate partial retrieval.","Upgrade or reconfigure the IMAP server to one supporting RFC 9394 PARTIAL or CONTEXT=SEARCH."],"exampleFix":"// before\nvar results = folder.Search (SearchOptions.None, query, new PartialRange (0, 10));\n\n// after\nif (client.Capabilities.HasFlag (ImapCapabilities.Partial)) {\n    var results = folder.Search (SearchOptions.None, query, new PartialRange (0, 10));\n} else {\n    var uids = folder.Search (query);\n    var page = uids.Skip (0).Take (10).ToArray ();\n}","handlingStrategy":"validation","validationCode":"bool canPartial = client.Capabilities.HasFlag (ImapCapabilities.Partial) ||\n    (client.Capabilities.HasFlag (ImapCapabilities.Context));\nif (!canPartial)\n    partialRange = null; // fall back to full search + client-side paging","typeGuard":null,"tryCatchPattern":"try {\n    results = folder.Search (SearchOptions.None, query, partialRange);\n} catch (NotSupportedException) {\n    var uids = folder.Search (query);\n    results = PageClientSide (uids, partialRange);\n}","preventionTips":["Gate every PartialRange usage behind an ImapCapabilities.Partial check.","Implement a generic client-side paging helper as the universal fallback.","Test integrations against servers with minimal capability sets."],"tags":["imap","mailkit","not-supported","partial-range","server-capability"],"backgroundTag":"unsupported-operation","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"}