jstedfast/MailKit · error · ArgumentException

Cannot search an empty header field name.

Error message

Cannot search an empty header field name.

What it means

SearchQuery.HeaderContains rejects an empty (zero-length) header field name with ArgumentException, because an IMAP HEADER search term needs a concrete header field (e.g. "Subject", "From"). An empty name would produce a meaningless or server-rejected search command, so MailKit fails fast.

Solutions

1. Validate the field name with string.IsNullOrWhiteSpace before calling HeaderContains and surface a UI/config error instead.
2. Trim user-supplied header names and reject empties at input time.
3. Use a default header (e.g. "Subject") when no field is specified, if that matches your semantics.

Example fix

// before
var query = SearchQuery.HeaderContains(inputField, inputText);
// after
var field = inputField?.Trim();
if (string.IsNullOrEmpty(field))
    throw new ArgumentException("Header field name is required.");
var query = SearchQuery.HeaderContains(field, inputText);

var field = inputField?.Trim();
if (string.IsNullOrEmpty(field))
    return null; // or report a user-facing validation error
var query = SearchQuery.HeaderContains(field, text);

static bool IsValidHeaderName(string field) =>
    !string.IsNullOrWhiteSpace(field);

try {
    query = SearchQuery.HeaderContains(field, text);
} catch (ArgumentException ex) when (ex.ParamName == nameof(field)) {
    userErrors.Add("Header field name cannot be empty.");
    query = null;
}

When it happens

Trigger: Calling SearchQuery.HeaderContains("", "text") — commonly the result of trimming user input to nothing, or a split of "field:value" strings where the field part is empty (e.g. ":value").

Common situations: Users entering ":something" or just spaces in a filter box; parsing header filters from strings like "=value"; blank form fields submitted for the header name.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• A metadata tag identifier cannot be empty.
• The host name cannot be empty.
• The keyword cannot be an empty string.
• Cannot search for null or empty keywords.
• Annotation attribute specifiers cannot be empty.

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

Appendix: source

Thrown at MailKit/Search/SearchQuery.cs:675

		/// </remarks>
		/// <returns>A <see cref="HeaderSearchQuery"/>.</returns>
		/// <param name="field">The header field to match against.</param>
		/// <param name="text">The text to match against.</param>
		/// <exception cref="System.ArgumentNullException">
		/// <para><paramref name="field"/> is <see langword="null" />.</para>
		/// <para>-or-</para>
		/// <para><paramref name="text"/> is <see langword="null" />.</para>
		/// </exception>
		/// <exception cref="System.ArgumentException">
		/// <paramref name="field"/> is empty.
		/// </exception>
		public static HeaderSearchQuery HeaderContains (string field, string text)
		{
			if (field == null)
				throw new ArgumentNullException (nameof (field));

			if (field.Length == 0)
				throw new ArgumentException ("Cannot search an empty header field name.", nameof (field));

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

			return new HeaderSearchQuery (field, text);
		}

		/// <summary>
		/// Match messages that are larger than the specified number of octets.
		/// </summary>
		/// <remarks>
		/// <para>Matches messages that are larger than the specified number of octets.</para>
		/// <note type="note">This is equivalent to the <c>LARGER</c> search key as defined in <a href="https://datatracker.ietf.org/doc/html/rfc3501#section-6.4.4">rfc3501</a>.</note>
		/// </remarks>
		/// <returns>A <see cref="NumericSearchQuery"/>.</returns>
		/// <param name="octets">The number of octets.</param>
		/// <exception cref="System.ArgumentOutOfRangeException">
		/// <paramref name="octets"/> is a negative value.

View on GitHub (pinned to 9d3859a785)