jstedfast/MailKit · error · NotSupportedException

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

Error message

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

What it means

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.

Solutions

  1. Guard with `client.Capabilities.HasFlag (ImapCapabilities.GMailExt1)` and use a fallback query (e.g. Keyword/CustomFlag search) when the extension is absent.
  2. Connect directly to Gmail (imap.gmail.com) so X-GM-EXT-1 is advertised.
  3. Migrate label filtering to standard IMAP flags/keywords if you must support heterogeneous servers.

Example fix

// before
var uids = folder.Search (SearchQuery.GMailLabels.Contains ("Important"));
// after
var uids = client.Capabilities.HasFlag (ImapCapabilities.GMailExt1)
    ? folder.Search (SearchQuery.GMailLabels.Contains ("Important"))
    : folder.Search (SearchQuery.Keyword ("Important"));
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.GMailLabels.Contains (label));
} catch (NotSupportedException) {
    uids = folder.Search (SearchQuery.Keyword (label));
}

Prevention

When it happens

Trigger: Calling ImapFolder.Search with `SearchQuery.GMailLabels.Contains("Important")` (or similar) while `Engine.Capabilities` does not include ImapCapabilities.GMailExt1.

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

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

Appendix: source

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

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

		string BuildQueryExpression (SearchQuery query, List<object> args, out string? charset)
		{

View on GitHub (pinned to 9d3859a785)