{"record":{"id":"72e5c28fc54bfc7e","repo":"jstedfast/MailKit","slug":"the-filter-search-term-is-not-supported-by-the-imap-server","errorCode":null,"errorMessage":"The FILTER search term is not supported by the IMAP server.","messagePattern":"The FILTER search term is not supported by the IMAP server\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolderSearch.cs","lineNumber":191,"sourceCode":"\t\t\t\tbuilder.Append (\"SINCE \");\n\t\t\t\tbuilder.Append (FormatDateTime (date.Date));\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.DeliveredBefore:\n\t\t\t\tdate = (DateSearchQuery) query;\n\t\t\t\tbuilder.Append (\"BEFORE \");\n\t\t\t\tbuilder.Append (FormatDateTime (date.Date));\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.DeliveredOn:\n\t\t\t\tdate = (DateSearchQuery) query;\n\t\t\t\tbuilder.Append (\"ON \");\n\t\t\t\tbuilder.Append (FormatDateTime (date.Date));\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.Draft:\n\t\t\t\tbuilder.Append (\"DRAFT\");\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.Filter:\n\t\t\t\tif ((Engine.Capabilities & ImapCapabilities.Filters) == 0)\n\t\t\t\t\tthrow new NotSupportedException (\"The FILTER search term is not supported by the IMAP server.\");\n\n\t\t\t\tfilter = (FilterSearchQuery) query;\n\t\t\t\tbuilder.Append (\"FILTER %S\");\n\t\t\t\targs.Add (filter.Name);\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.Flagged:\n\t\t\t\tbuilder.Append (\"FLAGGED\");\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.FromContains:\n\t\t\t\ttext = (TextSearchQuery) query;\n\t\t\t\tbuilder.Append (\"FROM \");\n\t\t\t\tAddTextArgument (builder, args, text.Text, ref charset);\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.Fuzzy:\n\t\t\t\tif ((Engine.Capabilities & ImapCapabilities.FuzzySearch) == 0)\n\t\t\t\t\tthrow new NotSupportedException (\"The FUZZY search term is not supported by the IMAP server.\");\n\n\t\t\t\tbuilder.Append (\"FUZZY \");","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolderSearch.cs#L173-L209","documentation":"BuildQuery throws this NotSupportedException when a SearchQuery.Filter term is included but the server lacks the FILTERS capability (a Dovecot/IETF draft extension). MailKit validates the capability while serializing the query so the search fails client-side rather than with an opaque server error. The FILTER term matches messages by a named server-side filter.","triggerScenarios":"Calling folder.Search(SearchQuery.Filter(name)) (FilterSearchQuery) on a server whose advertised capabilities exclude ImapCapabilities.Filters.","commonSituations":"Code copying Dovecot-specific filter-search examples and running it against Gmail/Exchange; servers where FILTERS was never enabled in configuration.","solutions":["Check (client.Capabilities & ImapCapabilities.Filters) != 0 before using SearchQuery.Filter.","Reimplement the filter logic client-side: fetch candidate messages and filter in application code.","Enable the FILTERS extension on the server (e.g. Dovecot config) if server-side filters are required."],"exampleFix":"// before\nvar uids = folder.Search(SearchQuery.Filter(\"spam-list\"));\n\n// after\nif ((client.Capabilities & ImapCapabilities.Filters) != 0)\n    uids = folder.Search(SearchQuery.Filter(\"spam-list\"));\nelse\n    uids = folder.Search(SearchQuery.NotSeen).Where(/* client-side filter */).ToArray();","handlingStrategy":"fallback","validationCode":"if ((client.Capabilities & ImapCapabilities.Filters) == 0)\n    return null; // use client-side filtering path instead","typeGuard":"bool SupportsFilters(ImapClient c) => (c.Capabilities & ImapCapabilities.Filters) != 0;","tryCatchPattern":"try {\n    return folder.Search(SearchQuery.Filter(name));\n} catch (NotSupportedException) {\n    return ClientSideFilter(folder, name);\n}","preventionTips":["Check FILTERS capability before constructing FilterSearchQuery.","Implement a client-side equivalent for server-only extensions you rely on.","Pin server configuration so FILTERS availability is stable per deployment."],"tags":["imap","search","capability-check","dovecot"],"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"}