jstedfast/MailKit · error · NotSupportedException

The ANNOTATION search term is not supported by the IMAP…

Error message

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

What it means

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.

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.

Example fix

// before
var uids = folder.Search(SearchQuery.Annotation("/comment", "value.priv", "hello"));

// after
if ((client.Capabilities & ImapCapabilities.Annotate) != 0)
    uids = folder.Search(SearchQuery.Annotation("/comment", "value.priv", "hello"));
else
    throw new InvalidOperationException("Server does not support ANNOTATE; use an alternative strategy");

Defensive patterns

Strategy: validation

Validate before calling

if ((client.Capabilities & ImapCapabilities.Annotate) == 0)
    throw new InvalidOperationException("ANNOTATE not supported");

Type guard

bool SupportsAnnotate(ImapClient c) => (c.Capabilities & ImapCapabilities.Annotate) != 0;

Try / catch

try {
    return folder.Search(SearchQuery.Annotation(entry, attr, value));
} catch (NotSupportedException ex) {
    logger.LogWarning(ex, "Annotation search unsupported");
    return Array.Empty<UniqueId>();
}

Prevention

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.

When it happens

Trigger: Calling folder.Search(SearchQuery.Annotation(entry, attribute, value)) or including an AnnotationSearchQuery in any composed query against a server without ImapCapabilities.Annotate.

Common situations: 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.

Related errors

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

Appendix: source

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

			UidSearchQuery uid;

			switch (query.Term) {
			case SearchTerm.All:
				builder.Append ("ALL");
				break;
			case SearchTerm.And:
				binary = (BinarySearchQuery) query;
				if (parens)
					builder.Append ('(');
				BuildQuery (builder, binary.Left, args, false, ref charset);
				builder.Append (' ');
				BuildQuery (builder, binary.Right, args, false, ref charset);
				if (parens)
					builder.Append (')');
				break;
			case SearchTerm.Annotation:
				if ((Engine.Capabilities & ImapCapabilities.Annotate) == 0)
					throw new NotSupportedException ("The ANNOTATION search term is not supported by the IMAP server.");

				annotation = (AnnotationSearchQuery) query;
				builder.Append ("ANNOTATION ");
				builder.Append (annotation.Entry);
				builder.Append (' ');
				builder.Append (annotation.Attribute);
				builder.Append (" %S");
				args.Add (annotation.Value);
				break;
			case SearchTerm.Answered:
				builder.Append ("ANSWERED");
				break;
			case SearchTerm.BccContains:
				text = (TextSearchQuery) query;
				builder.Append ("BCC ");
				AddTextArgument (builder, args, text.Text, ref charset);
				break;
			case SearchTerm.BodyContains:

View on GitHub (pinned to 9d3859a785)