{"record":{"id":"511f8f9cd194861a","repo":"jstedfast/MailKit","slug":"the-annotation-search-term-is-not-supported-by-the-imap","errorCode":null,"errorMessage":"The ANNOTATION search term is not supported by the IMAP server.","messagePattern":"The ANNOTATION search term is not supported by the IMAP server\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolderSearch.cs","lineNumber":140,"sourceCode":"\t\t\tUidSearchQuery uid;\n\n\t\t\tswitch (query.Term) {\n\t\t\tcase SearchTerm.All:\n\t\t\t\tbuilder.Append (\"ALL\");\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.And:\n\t\t\t\tbinary = (BinarySearchQuery) query;\n\t\t\t\tif (parens)\n\t\t\t\t\tbuilder.Append ('(');\n\t\t\t\tBuildQuery (builder, binary.Left, args, false, ref charset);\n\t\t\t\tbuilder.Append (' ');\n\t\t\t\tBuildQuery (builder, binary.Right, args, false, ref charset);\n\t\t\t\tif (parens)\n\t\t\t\t\tbuilder.Append (')');\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.Annotation:\n\t\t\t\tif ((Engine.Capabilities & ImapCapabilities.Annotate) == 0)\n\t\t\t\t\tthrow new NotSupportedException (\"The ANNOTATION search term is not supported by the IMAP server.\");\n\n\t\t\t\tannotation = (AnnotationSearchQuery) query;\n\t\t\t\tbuilder.Append (\"ANNOTATION \");\n\t\t\t\tbuilder.Append (annotation.Entry);\n\t\t\t\tbuilder.Append (' ');\n\t\t\t\tbuilder.Append (annotation.Attribute);\n\t\t\t\tbuilder.Append (\" %S\");\n\t\t\t\targs.Add (annotation.Value);\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.Answered:\n\t\t\t\tbuilder.Append (\"ANSWERED\");\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.BccContains:\n\t\t\t\ttext = (TextSearchQuery) query;\n\t\t\t\tbuilder.Append (\"BCC \");\n\t\t\t\tAddTextArgument (builder, args, text.Text, ref charset);\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.BodyContains:","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolderSearch.cs#L122-L158","documentation":"BuildQuery throws this NotSupportedException when a SearchQuery.Annotation term is compiled into an IMAP SEARCH command but the server does not advertise the ANNOTATE capability (RFC 5257). MailKit builds the query string client-side and checks capabilities so it can fail immediately instead of receiving a server BAD response. The ANNOTATION term searches message annotations by entry/attribute.","triggerScenarios":"Calling folder.Search(SearchQuery.Annotation(entry, attribute, value)) or including an AnnotationSearchQuery in any composed query against a server without ImapCapabilities.Annotate.","commonSituations":"Annotation search code developed against a server that supports ANNOTATE (e.g. some Cyrus builds) later run against Gmail, Exchange, or stock Dovecot, which do not.","solutions":["Check (client.Capabilities & ImapCapabilities.Annotate) != 0 before using SearchQuery.Annotation.","Replace the annotation search with metadata fetches or application-side filtering if annotations are not supported.","Move to an IMAP server that implements RFC 5257 ANNOTATE if annotation search is a hard requirement."],"exampleFix":"// before\nvar uids = folder.Search(SearchQuery.Annotation(\"/comment\", \"value.priv\", \"hello\"));\n\n// after\nif ((client.Capabilities & ImapCapabilities.Annotate) != 0)\n    uids = folder.Search(SearchQuery.Annotation(\"/comment\", \"value.priv\", \"hello\"));\nelse\n    throw new InvalidOperationException(\"Server does not support ANNOTATE; use an alternative strategy\");","handlingStrategy":"validation","validationCode":"if ((client.Capabilities & ImapCapabilities.Annotate) == 0)\n    throw new InvalidOperationException(\"ANNOTATE not supported\");","typeGuard":"bool SupportsAnnotate(ImapClient c) => (c.Capabilities & ImapCapabilities.Annotate) != 0;","tryCatchPattern":"try {\n    return folder.Search(SearchQuery.Annotation(entry, attr, value));\n} catch (NotSupportedException ex) {\n    logger.LogWarning(ex, \"Annotation search unsupported\");\n    return Array.Empty<UniqueId>();\n}","preventionTips":["Gate every non-RFC-3501 search term behind a capability check helper.","Test IMAP code against the lowest-common-denominator server in your environment.","Document which search terms your app requires and verify them at connect time."],"tags":["imap","search","capability-check","annotate"],"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"}