jstedfast/MailKit · error · NotSupportedException

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

Error message

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

What it means

BuildQuery throws this NotSupportedException when a SearchQuery.Fuzzy(...) term is used but the server does not advertise the SEARCH=FUZZY capability (RFC 6203). The FUZZY modifier relaxes matching of the wrapped search key. MailKit checks the capability during query serialization and throws immediately rather than letting the server return BAD.

Solutions

Check (client.Capabilities & ImapCapabilities.FuzzySearch) != 0 before wrapping a term in SearchQuery.Fuzzy.
Remove the Fuzzy wrapper and use the exact-match term instead when FUZZY is unavailable.
Implement approximate matching client-side (fetch results and rank with a fuzzy matcher in application code).

Example fix

// before
var uids = folder.Search(SearchQuery.Fuzzy(SearchQuery.SubjectContains("recipt")));

// after
var query = (client.Capabilities & ImapCapabilities.FuzzySearch) != 0
    ? SearchQuery.Fuzzy(SearchQuery.SubjectContains("recipt"))
    : SearchQuery.SubjectContains("recipt");
var uids = folder.Search(query);

Defensive patterns

Strategy: validation

Validate before calling

SearchQuery q = SearchQuery.SubjectContains(term);
if ((client.Capabilities & ImapCapabilities.FuzzySearch) != 0)
    q = SearchQuery.Fuzzy(q);

Type guard

bool SupportsFuzzy(ImapClient c) => (c.Capabilities & ImapCapabilities.FuzzySearch) != 0;

Try / catch

try {
    return folder.Search(SearchQuery.Fuzzy(inner));
} catch (NotSupportedException) {
    return folder.Search(inner); // exact match fallback
}

Prevention

Wrap capability-gated modifiers (Fuzzy) in helper builders that degrade gracefully.
Record server capabilities per environment in config/tests.
Avoid hard-coding extension terms when the IMAP provider varies.

When it happens

Trigger: Calling folder.Search(SearchQuery.Fuzzy(SearchQuery.SubjectContains("term"))) or any unary query wrapped in Fuzzy on a server without ImapCapabilities.FuzzySearch.

Common situations: Fuzzy-search code written against servers with SEARCH=FUZZY (e.g. Cyrus, newer Dovecot) deployed against Gmail or older servers that reject it.

Related errors

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

Appendix: source

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

			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 ");
				unary = (UnarySearchQuery) query;
				BuildQuery (builder, unary.Operand, args, true, ref charset);
				break;
			case SearchTerm.HeaderContains:
				header = (HeaderSearchQuery) query;
				builder.Append ("HEADER ");
				builder.Append (header.Field);
				builder.Append (' ');
				AddTextArgument (builder, args, header.Value, ref charset);
				break;
			case SearchTerm.Keyword:
				text = (TextSearchQuery) query;
				builder.Append ("KEYWORD ");
				AddKeywordArgument (builder, args, text.Text, ref charset);
				break;
			case SearchTerm.LargerThan:

View on GitHub (pinned to 9d3859a785)