{"record":{"id":"26edc325bfd63d1b","repo":"jstedfast/MailKit","slug":"the-imap-server-does-not-support-the-esearch-extension","errorCode":null,"errorMessage":"The IMAP server does not support the ESEARCH extension.","messagePattern":"The IMAP server does not support the ESEARCH extension\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolderSearch.cs","lineNumber":1045,"sourceCode":"\t\t/// </exception>\n\t\tpublic virtual async Task<SearchResults> SearchAsync (string query, CancellationToken cancellationToken = default)\n\t\t{\n\t\t\tvar ic = QueueSearchCommand (query, cancellationToken);\n\n\t\t\tawait Engine.RunAsync (ic).ConfigureAwait (false);\n\n\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","sourceCodeStart":1027,"sourceCodeEnd":1063,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolderSearch.cs#L1027-L1063","documentation":"MailKit throws this NotSupportedException from ImapFolder.QueueSearchCommand when a Search call passes SearchOptions other than None but the server never advertised the ESEARCH capability (RFC 4731) during connection. The ESEARCH extension is what allows servers to return counts, min/max ids, or save results instead of plain sequence numbers. Without it, only a plain SEARCH with no result options can be honored.","triggerScenarios":"Calling folder.Search(SearchOptions.Final | SearchOptions.Count, query, ...) or the async variants with options != SearchOptions.None on a server whose CAPABILITY response lacks ESEARCH. Note the check is skipped entirely when options == SearchOptions.None.","commonSituations":"Connecting to old or minimal IMAP servers (embedded mail servers, some proxies) that never implemented RFC 4731; code that always passes SearchOptions.Count out of habit; a server downgrade or new host where ESEARCH is not advertised.","solutions":["Check ImapClient.Capabilities.HasFlag(ImapCapabilities.ESearch) before passing non-None options; fall back to SearchOptions.None and post-process results client-side.","Call Search(SearchOptions.None, query) and compute Count/Final yourself from the returned unique IDs.","Switch to an IMAP server that supports ESEARCH (most modern servers: Dovecot, Cyrus, Exchange 2016+).","Wrap the Search call in try/catch for NotSupportedException and retry with options = SearchOptions.None."],"exampleFix":"// before\nvar results = folder.Search (SearchOptions.Count, query);\n\n// after\nvar options = client.Capabilities.HasFlag (ImapCapabilities.ESearch)\n    ? SearchOptions.Count\n    : SearchOptions.None;\nvar results = folder.Search (options, query);","handlingStrategy":"validation","validationCode":"bool canUseEsearch = client.Capabilities.HasFlag (ImapCapabilities.ESearch);\nif (!canUseEsearch && options != SearchOptions.None)\n    options = SearchOptions.None; // degrade before calling folder.Search","typeGuard":null,"tryCatchPattern":"try {\n    results = folder.Search (options, query);\n} catch (NotSupportedException) {\n    results = folder.Search (SearchOptions.None, query); // recompute client-side\n}","preventionTips":["Log ImapClient.Capabilities after connecting and assert required extensions (ESEARCH) in startup checks.","Feature-detect capabilities once and store a capabilities profile for the session.","Never hardcode non-None SearchOptions in shared code paths without a capability check."],"tags":["imap","mailkit","not-supported","esearch","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"}