jstedfast/MailKit · error · NotSupportedException

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

Error message

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

What it means

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.

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.

Example fix

// before
var uids = folder.Search (SearchQuery.GMailRaw ("is:unread in:inbox"));
// after
var uids = client.Capabilities.HasFlag (ImapCapabilities.GMailExt1)
    ? folder.Search (SearchQuery.GMailRaw ("is:unread in:inbox"))
    : folder.Search (SearchQuery.NotSeen.And (SearchQuery.All));

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.GMailRaw (raw));
} catch (NotSupportedException) {
    uids = folder.Search (TranslateRawToStandardQuery (raw));
}

Prevention

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.

When it happens

Trigger: Calling ImapFolder.Search with `SearchQuery.GMailRaw("in:inbox is:unread")` on a non-Gmail server (Capabilities missing ImapCapabilities.GMailExt1).

Common situations: 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.

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/0ba5130f372d29c7. Report an issue: GitHub.

Appendix: source

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

			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;
				builder.Append ("X-GM-RAW ");
				AddTextArgument (builder, args, text.Text, ref charset);
				break;
			}
		}

		string BuildQueryExpression (SearchQuery query, List<object> args, out string? charset)
		{
			var builder = new StringBuilder ();

			charset = null;

			BuildQuery (builder, query, args, false, ref charset);

			return builder.ToString ();
		}

View on GitHub (pinned to 9d3859a785)