jstedfast/MailKit · error · NotSupportedException

The X-GM-THRID search term is not supported by the IMAP…

Error message

The X-GM-THRID search term is not supported by the IMAP server.

What it means

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.

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.

Example fix

// before
var query = SearchQuery.GMailThreadId.Equals (threadId);
var uids = folder.Search (query);
// after
var query = client.Capabilities.HasFlag (ImapCapabilities.GMailExt1)
    ? SearchQuery.GMailThreadId.Equals (threadId)
    : SearchQuery.HeaderContains ("References", threadRootMessageId);
var uids = folder.Search (query);

Defensive patterns

Strategy: validation

Validate before calling

if (!client.Capabilities.HasFlag (ImapCapabilities.GMailExt1))
    throw new InvalidOperationException ("Server does not support Gmail search extensions; use a fallback query.");

Try / catch

try {
    uids = folder.Search (SearchQuery.GMailThreadId.Equals (threadId));
} catch (NotSupportedException) {
    uids = folder.Search (SearchQuery.HeaderContains ("References", threadRootMessageId));
}

Prevention

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.

When it happens

Trigger: Calling ImapFolder.Search with a query containing SearchQuery.GMailThreadId (e.g. `SearchQuery.GMailThreadId.Equals(threadId)`) on a server whose Capabilities lack ImapCapabilities.GMailExt1.

Common situations: Reusing Gmail-specific search logic against Dovecot/Exchange/other providers; using thread-id based conversation grouping code on non-Gmail accounts.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of jstedfast/MailKit@9d3859a785 (2026-09-15). Data as JSON: /api/errors/12a5f3956502c8a8. Report an issue: GitHub.

Appendix: source

Thrown at MailKit/Net/Imap/ImapFolderSearch.cs:375

			case SearchTerm.Younger:
				if ((Engine.Capabilities & ImapCapabilities.Within) == 0)
					throw new NotSupportedException ("The YOUNGER search term is not supported by the IMAP server.");

				numeric = (NumericSearchQuery) query;
				builder.Append ("YOUNGER ");
				builder.Append (numeric.Value.ToString (CultureInfo.InvariantCulture));
				break;
			case SearchTerm.GMailMessageId:
				if ((Engine.Capabilities & ImapCapabilities.GMailExt1) == 0)
					throw new NotSupportedException ("The X-GM-MSGID search term is not supported by the IMAP server.");

				numeric = (NumericSearchQuery) query;
				builder.Append ("X-GM-MSGID ");
				builder.Append (numeric.Value.ToString (CultureInfo.InvariantCulture));
				break;
			case SearchTerm.GMailThreadId:
				if ((Engine.Capabilities & ImapCapabilities.GMailExt1) == 0)
					throw new NotSupportedException ("The X-GM-THRID search term is not supported by the IMAP server.");

				numeric = (NumericSearchQuery) query;
				builder.Append ("X-GM-THRID ");
				builder.Append (numeric.Value.ToString (CultureInfo.InvariantCulture));
				break;
			case SearchTerm.GMailLabels:
				if ((Engine.Capabilities & ImapCapabilities.GMailExt1) == 0)
					throw new NotSupportedException ("The X-GM-LABELS search term is not supported by the IMAP server.");

				text = (TextSearchQuery) query;
				builder.Append ("X-GM-LABELS ");
				AddTextArgument (builder, args, text.Text, ref charset);
				break;
			case SearchTerm.GMailRaw:
				if ((Engine.Capabilities & ImapCapabilities.GMailExt1) == 0)
					throw new NotSupportedException ("The X-GM-RAW search term is not supported by the IMAP server.");

				text = (TextSearchQuery) query;

View on GitHub (pinned to 9d3859a785)