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

GetMetadata (single-tag path) needs the IMAP METADATA extension (RFC 5464). MailKit verifies ImapCapabilities.Metadata before queueing GETMETADATA and throws NotSupportedException if the server never advertised it, since the server cannot answer the command.

Solutions

1. Confirm (client.Capabilities & ImapCapabilities.Metadata) != 0 before calling GetMetadata
2. Use a different persistence mechanism (local database, IMAP flags, or custom headers) when metadata is unsupported
3. Enable the METADATA plugin/feature on your server (e.g. Dovecot's metadata plugin) if you control it
4. Catch NotSupportedException and fall back to defaults

Example fix

// before
var value = folder.GetMetadata(MetadataTag.Comment);
// after
if ((client.Capabilities & ImapCapabilities.Metadata) != 0)
    var value = folder.GetMetadata(MetadataTag.Comment);
else
    var value = null; // fallback: metadata unsupported

if ((client.Capabilities & ImapCapabilities.Metadata) == 0)
    throw new NotSupportedException("Server does not support IMAP METADATA");

bool SupportsMetadata(ImapClient c) => (c.Capabilities & ImapCapabilities.Metadata) != 0;

try {
    var value = folder.GetMetadata(MetadataTag.Comment);
} catch (NotSupportedException ex) {
    logger.LogWarning(ex, "METADATA unsupported; using default value");
    var value = null; // fallback default
}

When it happens

Trigger: Calling ImapFolder.GetMetadata with a MetadataTag on a server without METADATA in its CAPABILITY list.

Common situations: Reading server- or mailbox-level annotations (e.g. /comment, /specialuse) against servers lacking RFC 5464; older dovecot builds or commodity hosts without metadata enabled.

Related errors

• Value cannot be null. (Parameter 'options')
• Value cannot be null. (Parameter 'tags')
• Value cannot be null. (Parameter 'metadata')
• The IMAP server does not support the QUOTA extension.
• The IMAP server does not support the UTF8 extension.

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

Appendix: source

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

		/// </exception>
		/// <exception cref="ImapCommandException">
		/// The command failed.
		/// </exception>
		public override async Task RemoveAccessAsync (string name, CancellationToken cancellationToken = default)
		{
			var ic = QueueRemoveAccessCommand (name, cancellationToken);

			await Engine.RunAsync (ic).ConfigureAwait (false);

			ProcessRemoveAccessResponse (ic);
		}

		ImapCommand QueueGetMetadataCommand (MetadataTag tag, CancellationToken cancellationToken)
		{
			CheckState (false, false);

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

			var ic = new ImapCommand (Engine, cancellationToken, null, "GETMETADATA %F %S\r\n", this, 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)
		{
			var metadata = (MetadataCollection) ic.UserData!;

			ProcessResponseCodes (ic, null);

			ic.ThrowIfNotOk ("GETMETADATA");

View on GitHub (pinned to 9d3859a785)