jstedfast/MailKit · error · NotSupportedException

The FILTER search term is not supported by the IMAP server.

Error message

The FILTER search term is not supported by the IMAP server.

What it means

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.

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.

Example fix

// before
var uids = folder.Search(SearchQuery.Filter("spam-list"));

// after
if ((client.Capabilities & ImapCapabilities.Filters) != 0)
    uids = folder.Search(SearchQuery.Filter("spam-list"));
else
    uids = folder.Search(SearchQuery.NotSeen).Where(/* client-side filter */).ToArray();

Defensive patterns

Strategy: fallback

Validate before calling

if ((client.Capabilities & ImapCapabilities.Filters) == 0)
    return null; // use client-side filtering path instead

Type guard

bool SupportsFilters(ImapClient c) => (c.Capabilities & ImapCapabilities.Filters) != 0;

Try / catch

try {
    return folder.Search(SearchQuery.Filter(name));
} catch (NotSupportedException) {
    return ClientSideFilter(folder, name);
}

Prevention

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.

When it happens

Trigger: Calling folder.Search(SearchQuery.Filter(name)) (FilterSearchQuery) on a server whose advertised capabilities exclude ImapCapabilities.Filters.

Common situations: Code copying Dovecot-specific filter-search examples and running it against Gmail/Exchange; servers where FILTERS was never enabled in configuration.

Related errors

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

Appendix: source

Thrown at MailKit/Net/Imap/ImapFolderSearch.cs:191

				builder.Append ("SINCE ");
				builder.Append (FormatDateTime (date.Date));
				break;
			case SearchTerm.DeliveredBefore:
				date = (DateSearchQuery) query;
				builder.Append ("BEFORE ");
				builder.Append (FormatDateTime (date.Date));
				break;
			case SearchTerm.DeliveredOn:
				date = (DateSearchQuery) query;
				builder.Append ("ON ");
				builder.Append (FormatDateTime (date.Date));
				break;
			case SearchTerm.Draft:
				builder.Append ("DRAFT");
				break;
			case SearchTerm.Filter:
				if ((Engine.Capabilities & ImapCapabilities.Filters) == 0)
					throw new NotSupportedException ("The FILTER search term is not supported by the IMAP server.");

				filter = (FilterSearchQuery) query;
				builder.Append ("FILTER %S");
				args.Add (filter.Name);
				break;
			case SearchTerm.Flagged:
				builder.Append ("FLAGGED");
				break;
			case SearchTerm.FromContains:
				text = (TextSearchQuery) query;
				builder.Append ("FROM ");
				AddTextArgument (builder, args, text.Text, ref charset);
				break;
			case SearchTerm.Fuzzy:
				if ((Engine.Capabilities & ImapCapabilities.FuzzySearch) == 0)
					throw new NotSupportedException ("The FUZZY search term is not supported by the IMAP server.");

				builder.Append ("FUZZY ");

View on GitHub (pinned to 9d3859a785)