{"record":{"id":"0ba5130f372d29c7","repo":"jstedfast/MailKit","slug":"the-x-gm-raw-search-term-is-not-supported-by-the-imap-server","errorCode":null,"errorMessage":"The X-GM-RAW search term is not supported by the IMAP server.","messagePattern":"The X-GM-RAW search term is not supported by the IMAP server\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolderSearch.cs","lineNumber":391,"sourceCode":"\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{\n\t\t\tvar builder = new StringBuilder ();\n\n\t\t\tcharset = null;\n\n\t\t\tBuildQuery (builder, query, args, false, ref charset);\n\n\t\t\treturn builder.ToString ();\n\t\t}","sourceCodeStart":373,"sourceCodeEnd":409,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolderSearch.cs#L373-L409","documentation":"MailKit throws this NotSupportedException in ImapFolderSearch.BuildQuery when a SearchQuery uses SearchTerm.GMailRaw but the server does not advertise the GMailExt1 (X-GM-EXT-1) capability. X-GM-RAW passes raw Gmail search syntax, which only Gmail servers understand.","triggerScenarios":"Calling ImapFolder.Search with `SearchQuery.GMailRaw(\"in:inbox is:unread\")` on a non-Gmail server (Capabilities missing ImapCapabilities.GMailExt1).","commonSituations":"Porting Gmail web-style search strings into MailKit and running them against generic IMAP providers; shared mail-hosting setups that proxy Gmail but don't expose the extension.","solutions":["Check `client.Capabilities.HasFlag (ImapCapabilities.GMailExt1)` before using GMailRaw and translate the raw query into standard SearchQuery terms otherwise.","Use direct Gmail IMAP access when raw Gmail search syntax is required.","Rewrite the raw query as composable SearchQuery expressions (DateSent, Seen, etc.) for portability."],"exampleFix":"// before\nvar uids = folder.Search (SearchQuery.GMailRaw (\"is:unread in:inbox\"));\n// after\nvar uids = client.Capabilities.HasFlag (ImapCapabilities.GMailExt1)\n    ? folder.Search (SearchQuery.GMailRaw (\"is:unread in:inbox\"))\n    : folder.Search (SearchQuery.NotSeen.And (SearchQuery.All));","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.GMailRaw (raw));\n} catch (NotSupportedException) {\n    uids = folder.Search (TranslateRawToStandardQuery (raw));\n}","preventionTips":["Only use SearchQuery.GMailRaw when the server advertises X-GM-EXT-1.","Maintain a translator from Gmail raw syntax to composable SearchQuery terms for portability.","Assert server capabilities in integration tests before exercising Gmail-specific code paths."],"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"}