jstedfast/MailKit · error · NotSupportedException

The ImapFolder does not support annotations.

Error message

The ImapFolder does not support annotations.

What it means

ImapFolder.Store(uids, annotations) throws this NotSupportedException when the IMAP server did not advertise the ANNOTATE (or similar annotation) capability, so the folder's AnnotationAccess is AnnotationAccess.None. MailKit refuses to send a UID STORE command with annotation entries because the server would reject it. It is a capability check performed in QueueStoreCommands before any network command is queued.

Solutions

1. Check folder.AnnotationAccess != AnnotationAccess.None (and the client capabilities) before calling Store with annotations
2. If the server should support annotations, verify the IMAP server has the ANNOTATE extension enabled (e.g. Dovecot imap_annotation plugin, Cyrus 'annotations' option) and reconnect/re-open the folder
3. Skip or degrade annotation storage on servers without support, persisting metadata client-side instead

Example fix

// before
folder.Store(uids, annotations);
// after
if (folder.AnnotationAccess != AnnotationAccess.None)
    folder.Store(uids, annotations);
else
    // fall back: store annotations out-of-band or skip

if (folder.AnnotationAccess == AnnotationAccess.None)
    throw new SkipOperationException("Server does not support IMAP annotations.");
// safe now:
folder.Store(uids, annotations);

try {
    folder.Store(uids, annotations);
} catch (NotSupportedException) {
    // degrade: persist annotations client-side or skip
}

When it happens

Trigger: Calling Store(IList<UniqueId> uids, IList<Annotation> annotations) or its StoreAsync overload on an ImapFolder whose server lacks annotation support (AnnotationAccess == AnnotationAccess.None). Typical with servers like Gmail or older Dovecot builds that do not implement RFC 5257 ANNOTATE extension.

Common situations: Porting code that worked against a Cyrus/Dovecot server with annotations enabled to Gmail or Exchange; connecting to a server without the ANNOTATE capability listed in CAPABILITY response; assuming all IMAP servers support message annotations because the MailKit API exposes them.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• The IMAP server does not support annotations.
• The IMAP server does not support the ESORT extension.
• The IMAP server does not support the THREAD extension.
• Value cannot be null. (Parameter 'specifier')
• Annotation attribute specifiers cannot be empty.

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

Appendix: source

Thrown at MailKit/Net/Imap/ImapFolderAnnotations.cs:53

namespace MailKit.Net.Imap
{
	public partial class ImapFolder
	{
		IEnumerable<ImapCommand> QueueStoreCommands (IList<UniqueId> uids, ulong? modseq, IList<Annotation> annotations, CancellationToken cancellationToken)
		{
			if (uids == null)
				throw new ArgumentNullException (nameof (uids));

			if (modseq.HasValue && !supportsModSeq)
				throw new NotSupportedException ("The ImapFolder does not support mod-sequences.");

			if (annotations == null)
				throw new ArgumentNullException (nameof (annotations));

			CheckState (true, true);

			if (AnnotationAccess == AnnotationAccess.None)
				throw new NotSupportedException ("The ImapFolder does not support annotations.");

			if (uids.Count == 0 || annotations.Count == 0)
				return Array.Empty<ImapCommand> ();

			var builder = new StringBuilder ("UID STORE %s ");
			var values = new List<object> ();

			if (modseq.HasValue) {
				builder.Append ("(UNCHANGEDSINCE ");
				builder.Append (modseq.Value.ToString (CultureInfo.InvariantCulture));
				builder.Append (") ");
			}

			ImapUtils.FormatAnnotations (builder, annotations, values, true);
			builder.Append ("\r\n");

			var command = builder.ToString ();
			var args = values.ToArray ();

View on GitHub (pinned to 9d3859a785)