{"record":{"id":"3ca9ecdc4951c999","repo":"jstedfast/MailKit","slug":"the-imap-server-does-not-support-the-metadata-or-metadata","errorCode":null,"errorMessage":"The IMAP server does not support the METADATA or METADATA-SERVER extension.","messagePattern":"The IMAP server does not support the METADATA or METADATA-SERVER extension\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapClient.cs","lineNumber":2542,"sourceCode":"\t\t\tengine.Run (ic);\n\n\t\t\treturn ProcessGetMetadataResponse (ic, tag);\n\t\t}\n\n\t\tbool TryQueueGetMetadataCommand (MetadataOptions options, IEnumerable<MetadataTag> tags, CancellationToken cancellationToken, [NotNullWhen (true)] out ImapCommand? ic)\n\t\t{\n\t\t\tif (options == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (options));\n\n\t\t\tif (tags == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (tags));\n\n\t\t\tCheckDisposed ();\n\t\t\tCheckConnected ();\n\t\t\tCheckAuthenticated ();\n\n\t\t\tif ((engine.Capabilities & (ImapCapabilities.Metadata | ImapCapabilities.MetadataServer)) == 0)\n\t\t\t\tthrow new NotSupportedException (\"The IMAP server does not support the METADATA or METADATA-SERVER extension.\");\n\n\t\t\tvar command = new StringBuilder (\"GETMETADATA \\\"\\\"\");\n\t\t\tvar args = new List<object> ();\n\t\t\tbool hasOptions = false;\n\n\t\t\tif (options.MaxSize.HasValue || options.Depth != 0) {\n\t\t\t\tcommand.Append (\" (\");\n\t\t\t\tif (options.MaxSize.HasValue) {\n\t\t\t\t\tcommand.Append (\"MAXSIZE \");\n\t\t\t\t\tcommand.Append (options.MaxSize.Value.ToString (CultureInfo.InvariantCulture));\n\t\t\t\t\tcommand.Append (' ');\n\t\t\t\t}\n\t\t\t\tif (options.Depth > 0) {\n\t\t\t\t\tcommand.Append (\"DEPTH \");\n\t\t\t\t\tcommand.Append (options.Depth == int.MaxValue ? \"infinity\" : \"1\");\n\t\t\t\t\tcommand.Append (' ');\n\t\t\t\t}\n\t\t\t\tcommand[command.Length - 1] = ')';","sourceCodeStart":2524,"sourceCodeEnd":2560,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapClient.cs#L2524-L2560","documentation":"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.","triggerScenarios":"Calling ImapClient.GetMetadata with MetadataOptions (MaxSize, Depth, etc.) against a server lacking ImapCapabilities.Metadata and ImapCapabilities.MetadataServer.","commonSituations":"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.","solutions":["Gate the call on client.Capabilities.HasFlag(ImapCapabilities.Metadata) || HasFlag(ImapCapabilities.MetadataServer).","Fall back to the legacy ANNOTATEMESSAGE extension (ImapCapabilities.Annotation) if the server offers it instead.","Enable METADATA on the server (Dovecot imap_metadata, or upgrade the IMAP server).","Wrap in try/catch on NotSupportedException to degrade gracefully at runtime."],"exampleFix":"// before\nvar metadata = client.GetMetadata(new MetadataOptions { MaxSize = 1024 }, cancellationToken);\n\n// after\nvar caps = client.Capabilities;\nif ((caps & (ImapCapabilities.Metadata | ImapCapabilities.MetadataServer)) != 0)\n    var metadata = client.GetMetadata(new MetadataOptions { MaxSize = 1024 }, cancellationToken);\nelse\n    // fallback path: skip metadata or use annotations\n","handlingStrategy":"validation","validationCode":"if ((client.Capabilities & (ImapCapabilities.Metadata | ImapCapabilities.MetadataServer)) == 0) {\n    // fall back to ANNOTATION extension or skip\n}","typeGuard":null,"tryCatchPattern":"try { return await client.GetMetadataAsync(options, token); } catch (NotSupportedException) { return await FallbackAnnotationsAsync(token); }","preventionTips":["Feature-detect METADATA once per connection and cache the result.","Design annotation features with a non-metadata fallback store.","Document server requirements (RFC 5464) for deployments."],"tags":["imap","metadata","unsupported-feature","capability-check"],"backgroundTag":"unsupported-operation","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"}