{"record":{"id":"a6bc137278c80c75","repo":"jstedfast/MailKit","slug":"the-x-gm-labels-search-term-is-not-supported-by-the-imap","errorCode":null,"errorMessage":"The X-GM-LABELS search term is not supported by the IMAP server.","messagePattern":"The X-GM-LABELS search term is not supported by the IMAP server\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolderSearch.cs","lineNumber":383,"sourceCode":"\t\t\tcase SearchTerm.GMailMessageId:\n\t\t\t\tif ((Engine.Capabilities & ImapCapabilities.GMailExt1) == 0)\n\t\t\t\t\tthrow new NotSupportedException (\"The X-GM-MSGID search term is not supported by the IMAP server.\");\n\n\t\t\t\tnumeric = (NumericSearchQuery) query;\n\t\t\t\tbuilder.Append (\"X-GM-MSGID \");\n\t\t\t\tbuilder.Append (numeric.Value.ToString (CultureInfo.InvariantCulture));\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.GMailThreadId:\n\t\t\t\tif ((Engine.Capabilities & ImapCapabilities.GMailExt1) == 0)\n\t\t\t\t\tthrow new NotSupportedException (\"The X-GM-THRID search term is not supported by the IMAP server.\");\n\n\t\t\t\tnumeric = (NumericSearchQuery) query;\n\t\t\t\tbuilder.Append (\"X-GM-THRID \");\n\t\t\t\tbuilder.Append (numeric.Value.ToString (CultureInfo.InvariantCulture));\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.GMailLabels:\n\t\t\t\tif ((Engine.Capabilities & ImapCapabilities.GMailExt1) == 0)\n\t\t\t\t\tthrow new NotSupportedException (\"The X-GM-LABELS search term is not supported by the IMAP server.\");\n\n\t\t\t\ttext = (TextSearchQuery) query;\n\t\t\t\tbuilder.Append (\"X-GM-LABELS \");\n\t\t\t\tAddTextArgument (builder, args, text.Text, ref charset);\n\t\t\t\tbreak;\n\t\t\tcase SearchTerm.GMailRaw:\n\t\t\t\tif ((Engine.Capabilities & ImapCapabilities.GMailExt1) == 0)\n\t\t\t\t\tthrow new NotSupportedException (\"The X-GM-RAW search term is not supported by the IMAP server.\");\n\n\t\t\t\ttext = (TextSearchQuery) query;\n\t\t\t\tbuilder.Append (\"X-GM-RAW \");\n\t\t\t\tAddTextArgument (builder, args, text.Text, ref charset);\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\n\t\tstring BuildQueryExpression (SearchQuery query, List<object> args, out string? charset)\n\t\t{","sourceCodeStart":365,"sourceCodeEnd":401,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolderSearch.cs#L365-L401","documentation":"MailKit throws this NotSupportedException in ImapFolderSearch.BuildQuery when a SearchQuery uses SearchTerm.GMailLabels but the IMAP server lacks the GMailExt1 (X-GM-EXT-1) capability. The X-GM-LABELS search key only exists on Gmail, so the query cannot be built for other servers.","triggerScenarios":"Calling ImapFolder.Search with `SearchQuery.GMailLabels.Contains(\"Important\")` (or similar) while `Engine.Capabilities` does not include ImapCapabilities.GMailExt1.","commonSituations":"Label-based filtering code run against corporate IMAP servers (Exchange, Zimbra without the extension), or against Gmail accounts accessed through a proxy/gateway that strips the capability.","solutions":["Guard with `client.Capabilities.HasFlag (ImapCapabilities.GMailExt1)` and use a fallback query (e.g. Keyword/CustomFlag search) when the extension is absent.","Connect directly to Gmail (imap.gmail.com) so X-GM-EXT-1 is advertised.","Migrate label filtering to standard IMAP flags/keywords if you must support heterogeneous servers."],"exampleFix":"// before\nvar uids = folder.Search (SearchQuery.GMailLabels.Contains (\"Important\"));\n// after\nvar uids = client.Capabilities.HasFlag (ImapCapabilities.GMailExt1)\n    ? folder.Search (SearchQuery.GMailLabels.Contains (\"Important\"))\n    : folder.Search (SearchQuery.Keyword (\"Important\"));","handlingStrategy":"validation","validationCode":"if (!client.Capabilities.HasFlag (ImapCapabilities.GMailExt1))\n    throw new InvalidOperationException (\"Server does not support Gmail search extensions; use a fallback query.\");","typeGuard":null,"tryCatchPattern":"try {\n    uids = folder.Search (SearchQuery.GMailLabels.Contains (label));\n} catch (NotSupportedException) {\n    uids = folder.Search (SearchQuery.Keyword (label));\n}","preventionTips":["Check ImapCapabilities.GMailExt1 before label-based searches.","Prefer standard IMAP keywords/flags when targeting multiple providers.","Test against non-Gmail servers in CI to catch capability assumptions."],"tags":["imap","gmail","capability-check","not-supported"],"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"}