jstedfast/MailKit · error · NotSupportedException

One ore more requests included annotations but the IMAP…

Error message

One ore more requests included annotations but the IMAP server does not support annotations.

What it means

The annotation request list contains annotations, but the connected IMAP server did not advertise the ANNOTATE capability (RFC 5257). MailKit refuses client-side rather than sending a command the server would fail. Thrown as NotSupportedException from the annotation argument-validation path in ImapFolder.

Solutions

1. Check (imapClient.Capabilities & ImapCapabilities.Annotate) != 0 before attaching Annotations to requests
2. Strip the Annotations property from requests when the capability is missing, or skip annotation calls entirely
3. Verify you connected to the intended server (feature flags per environment)
4. Wrap in try/catch (NotSupportedException) to degrade gracefully

Example fix

// before
request.Annotations = new[] { new Annotation("/comment") { ... } };
folder.SetAnnotations(new[] { request });
// after
if ((client.Capabilities & ImapCapabilities.Annotate) != 0)
    request.Annotations = new[] { new Annotation("/comment") { ... } };
folder.SetAnnotations(new[] { request });

bool canAnnotate = (client.Capabilities & ImapCapabilities.Annotate) != 0;
if (!canAnnotate)
    requests = requests.Select(r => { r.Annotations = null; return r; }).ToList();

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

try { folder.SetAnnotations(requests); }
catch (NotSupportedException) { log.LogWarning("Server lacks ANNOTATE; skipping annotations"); }

When it happens

Trigger: Setting request.Annotations (non-empty) on a folder whose ImapClient.Capabilities lacks ImapCapabilities.Annotate, then calling SetAnnotations/Store with those requests.

Common situations: Developers assume all servers support annotations; connecting to Gmail/Exchange/outlook.com which do not implement ANNOTATE; capability check done once against a different server in a test environment.

Related errors

• The IMAP server does not support the COMPRESS extension.
• The IMAP server does not support the STARTTLS extension.
• The IMAP server does not support the QRESYNC extension.
• The IMAP server does not support the UTF8=ACCEPT extension.
• The IMAP server does not support the ID extension.

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

Appendix: source

Thrown at MailKit/Net/Imap/ImapFolder.cs:4611

			return ProcessAppendResponse (ic);
		}

		void ValidateArguments (FormatOptions options, IList<IAppendRequest> requests)
		{
			if (options == null)
				throw new ArgumentNullException (nameof (options));

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

			for (int i = 0; i < requests.Count; i++) {
				if (requests[i] == null)
					throw new ArgumentException ("One or more of the requests is null.");

				var annotations = requests[i].Annotations;
				if (annotations != null && annotations.Count > 0 && (Engine.Capabilities & ImapCapabilities.Annotate) == 0)
					throw new NotSupportedException ("One ore more requests included annotations but the IMAP server does not support annotations.");
			}

			CheckState (false, false);
		}

		ImapCommand QueueMultiAppendCommand (FormatOptions options, IList<IAppendRequest> requests, CancellationToken cancellationToken)
		{
			var format = CreateAppendOptions (options);
			var builder = new StringBuilder ("APPEND %F");
			var list = new List<object> {
				this
			};

			for (int i = 0; i < requests.Count; i++) {
				var keywords = requests[i].Keywords;
				int numKeywords = keywords != null ? keywords.Count : 0;

				builder.Append (' ');

View on GitHub (pinned to 9d3859a785)