jstedfast/MailKit · error · NotSupportedException

The IMAP server does not support the METADATA or…

Error message

The IMAP server does not support the METADATA or METADATA-SERVER extension.

What it means

This GetMetadata overload (taking options such as MaxSize/Depth) throws the same NotSupportedException when the server advertises neither METADATA nor METADATA-SERVER. MailKit pre-validates the RFC 5464 capability before building the GETMETADATA command with options.

Solutions

1. Gate the call on client.Capabilities.HasFlag(ImapCapabilities.Metadata) || HasFlag(ImapCapabilities.MetadataServer).
2. Fall back to the legacy ANNOTATEMESSAGE extension (ImapCapabilities.Annotation) if the server offers it instead.
3. Enable METADATA on the server (Dovecot imap_metadata, or upgrade the IMAP server).
4. Wrap in try/catch on NotSupportedException to degrade gracefully at runtime.

Example fix

// before
var metadata = client.GetMetadata(new MetadataOptions { MaxSize = 1024 }, cancellationToken);

// after
var caps = client.Capabilities;
if ((caps & (ImapCapabilities.Metadata | ImapCapabilities.MetadataServer)) != 0)
    var metadata = client.GetMetadata(new MetadataOptions { MaxSize = 1024 }, cancellationToken);
else
    // fallback path: skip metadata or use annotations

if ((client.Capabilities & (ImapCapabilities.Metadata | ImapCapabilities.MetadataServer)) == 0) {
    // fall back to ANNOTATION extension or skip
}

try { return await client.GetMetadataAsync(options, token); } catch (NotSupportedException) { return await FallbackAnnotationsAsync(token); }

When it happens

Trigger: Calling ImapClient.GetMetadata with MetadataOptions (MaxSize, Depth, etc.) against a server lacking ImapCapabilities.Metadata and ImapCapabilities.MetadataServer.

Common situations: Enumerating per-mailbox annotations on legacy IMAP servers; code written against Gmail/Dovecot-with-metadata then deployed to a server without RFC 5464; proxies/gateways stripping capabilities.

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 the METADATA extension.
• The IMAP server does not support the STARTTLS extension.
• The IMAP server does not support the COMPRESS extension.
• The IMAP server does not support the METADATA extension.
• Value cannot be null. (Parameter 'options')

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

Appendix: source

Thrown at MailKit/Net/Imap/ImapClient.cs:2542

			engine.Run (ic);

			return ProcessGetMetadataResponse (ic, tag);
		}

		bool TryQueueGetMetadataCommand (MetadataOptions options, IEnumerable<MetadataTag> tags, CancellationToken cancellationToken, [NotNullWhen (true)] out ImapCommand? ic)
		{
			if (options == null)
				throw new ArgumentNullException (nameof (options));

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

			CheckDisposed ();
			CheckConnected ();
			CheckAuthenticated ();

			if ((engine.Capabilities & (ImapCapabilities.Metadata | ImapCapabilities.MetadataServer)) == 0)
				throw new NotSupportedException ("The IMAP server does not support the METADATA or METADATA-SERVER extension.");

			var command = new StringBuilder ("GETMETADATA \"\"");
			var args = new List<object> ();
			bool hasOptions = false;

			if (options.MaxSize.HasValue || options.Depth != 0) {
				command.Append (" (");
				if (options.MaxSize.HasValue) {
					command.Append ("MAXSIZE ");
					command.Append (options.MaxSize.Value.ToString (CultureInfo.InvariantCulture));
					command.Append (' ');
				}
				if (options.Depth > 0) {
					command.Append ("DEPTH ");
					command.Append (options.Depth == int.MaxValue ? "infinity" : "1");
					command.Append (' ');
				}
				command[command.Length - 1] = ')';

View on GitHub (pinned to 9d3859a785)