{"record":{"id":"0675d1aa39f61863","repo":"jstedfast/MailKit","slug":"the-fuzzy-search-term-is-not-supported-by-the-imap-server","errorCode":null,"errorMessage":"The FUZZY search term is not supported by the IMAP server.","messagePattern":"The FUZZY search term is not supported by the IMAP server\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolderSearch.cs","lineNumber":207,"sourceCode":"\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 \");\n\t\t\t\tunary = (UnarySearchQuery) query;\n\t\t\t\tBuildQuery (builder, unary.Operand, args, true, ref charset);\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.HeaderContains:\n\t\t\t\theader = (HeaderSearchQuery) query;\n\t\t\t\tbuilder.Append (\"HEADER \");\n\t\t\t\tbuilder.Append (header.Field);\n\t\t\t\tbuilder.Append (' ');\n\t\t\t\tAddTextArgument (builder, args, header.Value, ref charset);\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.Keyword:\n\t\t\t\ttext = (TextSearchQuery) query;\n\t\t\t\tbuilder.Append (\"KEYWORD \");\n\t\t\t\tAddKeywordArgument (builder, args, text.Text, ref charset);\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.LargerThan:","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolderSearch.cs#L189-L225","documentation":"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.","triggerScenarios":"Calling folder.Search(SearchQuery.Fuzzy(SearchQuery.SubjectContains(\"term\"))) or any unary query wrapped in Fuzzy on a server without ImapCapabilities.FuzzySearch.","commonSituations":"Fuzzy-search code written against servers with SEARCH=FUZZY (e.g. Cyrus, newer Dovecot) deployed against Gmail or older servers that reject it.","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)."],"exampleFix":"// before\nvar uids = folder.Search(SearchQuery.Fuzzy(SearchQuery.SubjectContains(\"recipt\")));\n\n// after\nvar query = (client.Capabilities & ImapCapabilities.FuzzySearch) != 0\n    ? SearchQuery.Fuzzy(SearchQuery.SubjectContains(\"recipt\"))\n    : SearchQuery.SubjectContains(\"recipt\");\nvar uids = folder.Search(query);","handlingStrategy":"validation","validationCode":"SearchQuery q = SearchQuery.SubjectContains(term);\nif ((client.Capabilities & ImapCapabilities.FuzzySearch) != 0)\n    q = SearchQuery.Fuzzy(q);","typeGuard":"bool SupportsFuzzy(ImapClient c) => (c.Capabilities & ImapCapabilities.FuzzySearch) != 0;","tryCatchPattern":"try {\n    return folder.Search(SearchQuery.Fuzzy(inner));\n} catch (NotSupportedException) {\n    return folder.Search(inner); // exact match fallback\n}","preventionTips":["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."],"tags":["imap","search","capability-check","fuzzy-search"],"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"}