{"record":{"id":"12a5f3956502c8a8","repo":"jstedfast/MailKit","slug":"the-x-gm-thrid-search-term-is-not-supported-by-the-imap","errorCode":null,"errorMessage":"The X-GM-THRID search term is not supported by the IMAP server.","messagePattern":"The X-GM-THRID search term is not supported by the IMAP server\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolderSearch.cs","lineNumber":375,"sourceCode":"\t\t\tcase SearchTerm.Younger:\n\t\t\t\tif ((Engine.Capabilities & ImapCapabilities.Within) == 0)\n\t\t\t\t\tthrow new NotSupportedException (\"The YOUNGER search term is not supported by the IMAP server.\");\n\n\t\t\t\tnumeric = (NumericSearchQuery) query;\n\t\t\t\tbuilder.Append (\"YOUNGER \");\n\t\t\t\tbuilder.Append (numeric.Value.ToString (CultureInfo.InvariantCulture));\n\t\t\t\tbreak;\n\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;","sourceCodeStart":357,"sourceCodeEnd":393,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolderSearch.cs#L357-L393","documentation":"MailKit throws this NotSupportedException in ImapFolderSearch.BuildQuery when a SearchQuery uses SearchTerm.GMailThreadId but the server does not advertise the GMailExt1 (X-GM-EXT-1) capability. X-GM-THRID is a Gmail-only search key, so MailKit refuses to emit it for servers that cannot handle it.","triggerScenarios":"Calling ImapFolder.Search with a query containing SearchQuery.GMailThreadId (e.g. `SearchQuery.GMailThreadId.Equals(threadId)`) on a server whose Capabilities lack ImapCapabilities.GMailExt1.","commonSituations":"Reusing Gmail-specific search logic against Dovecot/Exchange/other providers; using thread-id based conversation grouping code on non-Gmail accounts.","solutions":["Verify `client.Capabilities.HasFlag (ImapCapabilities.GMailExt1)` before using GMailThreadId and branch to an alternative query when absent.","Authenticate against Gmail itself if the Gmail extension is required — only Gmail servers advertise X-GM-EXT-1.","Replace the GMailThreadId term with an equivalent such as searching References/In-Reply-To headers for the thread's message IDs."],"exampleFix":"// before\nvar query = SearchQuery.GMailThreadId.Equals (threadId);\nvar uids = folder.Search (query);\n// after\nvar query = client.Capabilities.HasFlag (ImapCapabilities.GMailExt1)\n    ? SearchQuery.GMailThreadId.Equals (threadId)\n    : SearchQuery.HeaderContains (\"References\", threadRootMessageId);\nvar uids = folder.Search (query);","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.GMailThreadId.Equals (threadId));\n} catch (NotSupportedException) {\n    uids = folder.Search (SearchQuery.HeaderContains (\"References\", threadRootMessageId));\n}","preventionTips":["Gate all SearchQuery.GMail* usage behind capability checks.","Keep a non-Gmail fallback query path in your search layer.","Log server capabilities at startup to catch environment mismatches early."],"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"}