jstedfast/MailKit · error · ArgumentOutOfRangeException

The specified threading algorithm is not supported.

Error message

The specified threading algorithm is not supported.

What it means

MailKit throws this ArgumentOutOfRangeException when the requested ThreadingAlgorithm (e.g. References or OrderedSubject) is not among the threading algorithms the server advertised via its THREAD=... capability list. The server supports threading, but not this specific algorithm.

Solutions

  1. Check client.ThreadingAlgorithms.Contains (algorithm) before calling Thread/ThreadAsync
  2. Request the other algorithm the server does advertise (References is the most widely supported)
  3. Thread messages client-side when the needed algorithm is unavailable

Example fix

// before
var threads = folder.Thread (ThreadingAlgorithm.OrderedSubject, query);
// after
if (client.ThreadingAlgorithms.Contains (ThreadingAlgorithm.OrderedSubject))
    var threads = folder.Thread (ThreadingAlgorithm.OrderedSubject, query);
else if (client.ThreadingAlgorithms.Contains (ThreadingAlgorithm.References))
    var threads = folder.Thread (ThreadingAlgorithm.References, query);
Defensive patterns

Strategy: validation

Validate before calling

bool algorithmSupported = client.ThreadingAlgorithms.Contains (algorithm);

Try / catch

try { threads = folder.Thread (algorithm, query); } catch (ArgumentOutOfRangeException) { threads = folder.Thread (client.ThreadingAlgorithms.First (), query); }

Prevention

When it happens

Trigger: Calling Thread/ThreadAsync with ThreadingAlgorithm.OrderedSubject (or References) when Engine.ThreadingAlgorithms (derived from THREAD=REFERENCES / THREAD=ORDEREDSUBJECT capabilities) does not contain that value.

Common situations: Servers advertising only THREAD=REFERENCES when code requests OrderedSubject, or vice versa; hard-coding an algorithm without checking ImapClient.ThreadingAlgorithms.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

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

		/// </exception>
		/// <exception cref="ImapCommandException">
		/// The server replied with a NO or BAD response.
		/// </exception>
		public override Task<SearchResults> SortAsync (SearchOptions options, SearchQuery query, IList<OrderBy> orderBy, PartialRange partialRange, CancellationToken cancellationToken = default)
		{
			if ((options & SearchOptions.All) != 0)
				throw new ArgumentException ("The SearchOptions.All flag cannot be combined with a partial range.", nameof (options));

			return SortAsync (options, query, orderBy, partialRange, true, cancellationToken);
		}

		ImapCommand QueueThreadCommand (ThreadingAlgorithm algorithm, SearchQuery query, CancellationToken cancellationToken, out string? charset)
		{
			if ((Engine.Capabilities & ImapCapabilities.Thread) == 0)
				throw new NotSupportedException ("The IMAP server does not support the THREAD extension.");

			if (!Engine.ThreadingAlgorithms.Contains (algorithm))
				throw new ArgumentOutOfRangeException (nameof (algorithm), "The specified threading algorithm is not supported.");

			if (query == null)
				throw new ArgumentNullException (nameof (query));

			CheckState (true, false);

			var method = algorithm.ToString ().ToUpperInvariant ();
			var args = new List<object> ();
			var optimized = query.Optimize (new ImapSearchQueryOptimizer ());
			var expr = BuildQueryExpression (optimized, args, out charset);
			var command = $"UID THREAD {method} {charset ?? "US-ASCII"} {expr}\r\n";

			var ic = new ImapCommand (Engine, cancellationToken, this, command, args.ToArray ());
			ic.RegisterUntaggedHandler ("THREAD", ImapUtils.UntaggedThreadHandler);

			Engine.QueueCommand (ic);

			return ic;

View on GitHub (pinned to 9d3859a785)