{"record":{"id":"514c4016ec87faea","repo":"jstedfast/MailKit","slug":"the-imap-server-does-not-support-the-metadata-extension-514c40","errorCode":null,"errorMessage":"The IMAP server does not support the METADATA extension.","messagePattern":"The IMAP server does not support the METADATA extension\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolder.cs","lineNumber":3174,"sourceCode":"\t\t/// </exception>\n\t\t/// <exception cref=\"ImapCommandException\">\n\t\t/// The command failed.\n\t\t/// </exception>\n\t\tpublic override async Task RemoveAccessAsync (string name, CancellationToken cancellationToken = default)\n\t\t{\n\t\t\tvar ic = QueueRemoveAccessCommand (name, cancellationToken);\n\n\t\t\tawait Engine.RunAsync (ic).ConfigureAwait (false);\n\n\t\t\tProcessRemoveAccessResponse (ic);\n\t\t}\n\n\t\tImapCommand QueueGetMetadataCommand (MetadataTag tag, CancellationToken cancellationToken)\n\t\t{\n\t\t\tCheckState (false, false);\n\n\t\t\tif ((Engine.Capabilities & ImapCapabilities.Metadata) == 0)\n\t\t\t\tthrow new NotSupportedException (\"The IMAP server does not support the METADATA extension.\");\n\n\t\t\tvar ic = new ImapCommand (Engine, cancellationToken, null, \"GETMETADATA %F %S\\r\\n\", this, tag.Id);\n\t\t\tic.RegisterUntaggedHandler (\"METADATA\", ImapUtils.UntaggedMetadataHandler);\n\t\t\tvar metadata = new MetadataCollection ();\n\t\t\tic.UserData = metadata;\n\n\t\t\tEngine.QueueCommand (ic);\n\n\t\t\treturn ic;\n\t\t}\n\n\t\tstring? ProcessGetMetadataResponse (ImapCommand ic, MetadataTag tag)\n\t\t{\n\t\t\tvar metadata = (MetadataCollection) ic.UserData!;\n\n\t\t\tProcessResponseCodes (ic, null);\n\n\t\t\tic.ThrowIfNotOk (\"GETMETADATA\");","sourceCodeStart":3156,"sourceCodeEnd":3192,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolder.cs#L3156-L3192","documentation":"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.","triggerScenarios":"Calling ImapFolder.GetMetadata with a MetadataTag on a server without METADATA in its CAPABILITY list.","commonSituations":"Reading server- or mailbox-level annotations (e.g. /comment, /specialuse) against servers lacking RFC 5464; older dovecot builds or commodity hosts without metadata enabled.","solutions":["Confirm (client.Capabilities & ImapCapabilities.Metadata) != 0 before calling GetMetadata","Use a different persistence mechanism (local database, IMAP flags, or custom headers) when metadata is unsupported","Enable the METADATA plugin/feature on your server (e.g. Dovecot's metadata plugin) if you control it","Catch NotSupportedException and fall back to defaults"],"exampleFix":"// before\nvar value = folder.GetMetadata(MetadataTag.Comment);\n// after\nif ((client.Capabilities & ImapCapabilities.Metadata) != 0)\n    var value = folder.GetMetadata(MetadataTag.Comment);\nelse\n    var value = null; // fallback: metadata unsupported","handlingStrategy":"validation","validationCode":"if ((client.Capabilities & ImapCapabilities.Metadata) == 0)\n    throw new NotSupportedException(\"Server does not support IMAP METADATA\");","typeGuard":"bool SupportsMetadata(ImapClient c) => (c.Capabilities & ImapCapabilities.Metadata) != 0;","tryCatchPattern":"try {\n    var value = folder.GetMetadata(MetadataTag.Comment);\n} catch (NotSupportedException ex) {\n    logger.LogWarning(ex, \"METADATA unsupported; using default value\");\n    var value = null; // fallback default\n}","preventionTips":["Gate all metadata calls on ImapCapabilities.Metadata","Enable the server's metadata plugin when you control the deployment","Provide local-storage fallbacks for annotations","Verify capabilities right after connect and cache the result"],"tags":["imap","metadata","not-supported","mailkit"],"backgroundTag":"feature-not-enabled","analyzedSha":"9d3859a7855e3e17582c07fd01972b8e262bf176","analyzedAt":"2026-09-15T15:46:11.592Z","contentChangedAt":"2026-09-15T15:46:11.592Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}