jstedfast/MailKit · error · NotSupportedException

The IMAP server does not support the METADATA extension.

Error message

The IMAP server does not support the METADATA extension.

What it means

ImapClient.GetMetadata throws this NotSupportedException when the connected server did not advertise the METADATA or METADATA-SERVER capability (RFC 5464). MailKit checks engine.Capabilities before sending the GETMETADATA command rather than letting the server return a BAD response. It means the server simply cannot serve IMAP metadata entries.

Solutions

Check client.Capabilities.HasFlag(ImapCapabilities.Metadata) || HasFlag(ImapCapabilities.MetadataServer) before calling GetMetadata and skip or branch when absent.
Use server-level fallbacks: read the server vendor/info via the ID extension (ImapCapabilities.Id) instead of metadata entries like /shared/comment.
If you control the server, enable the METADATA extension (e.g. Dovecot: imap_metadata=yes plus metadata storage config).
Cache the capability check per connection to avoid repeated probes.

Example fix

// before
var metadata = client.GetMetadata(cancellationToken);

// after
if (client.Capabilities.HasFlag(ImapCapabilities.Metadata) || client.Capabilities.HasFlag(ImapCapabilities.MetadataServer)) {
    var metadata = client.GetMetadata(cancellationToken);
} else {
    var metadata = null; // server does not support METADATA; use ID/fallbacks
}

Defensive patterns

Strategy: validation

Validate before calling

bool canGetMetadata = (client.Capabilities & (ImapCapabilities.Metadata | ImapCapabilities.MetadataServer)) != 0;
if (!canGetMetadata) return null; // skip metadata path

Try / catch

try { return client.GetMetadata(token); } catch (NotSupportedException) { return null; }

Prevention

Always probe Capabilities after Connect/Authenticate before using extension commands.
Centralize capability checks in a helper instead of calling extension APIs directly.
Log unsupported extensions per server to plan feature fallbacks.

When it happens

Trigger: Calling ImapClient.GetMetadata on a connection whose server lacks both ImapCapabilities.Metadata and ImapCapabilities.MetadataServer; the check happens after CheckDisposed/CheckConnected/CheckAuthenticated, so it fires only on a live authenticated session.

Common situations: Connecting to IMAP servers that never implemented RFC 5464 (many older Courier/Dovecot builds without metadata enabled, Exchange in some configurations); assuming all servers support per-server metadata like /shared/comment.

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

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

Appendix: source

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

		{
			if (path == null)
				throw new ArgumentNullException (nameof (path));

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

			return engine.GetFolder (path, cancellationToken);
		}

		ImapCommand QueueGetMetadataCommand (MetadataTag tag, CancellationToken cancellationToken)
		{
			CheckDisposed ();
			CheckConnected ();
			CheckAuthenticated ();

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

			var ic = new ImapCommand (engine, cancellationToken, null, "GETMETADATA \"\" %S\r\n", tag.Id);
			ic.RegisterUntaggedHandler ("METADATA", ImapUtils.UntaggedMetadataHandler);
			var metadata = new MetadataCollection ();
			ic.UserData = metadata;

			engine.QueueCommand (ic);

			return ic;
		}

		string? ProcessGetMetadataResponse (ImapCommand ic, MetadataTag tag)
		{
			ic.ThrowIfNotOk ("GETMETADATA");

			var metadata = (MetadataCollection) ic.UserData!;
			string? value = null;

View on GitHub (pinned to 9d3859a785)