jstedfast/MailKit · error · ArgumentException

Cannot search an empty header field name.

Error message

Cannot search an empty header field name.

What it means

MailKit's HeaderSearchQuery constructor validates that the header field name used for a search (e.g. Subject, From) is a non-empty string. An empty string can never match a real IMAP header field, so the library throws ArgumentException immediately instead of producing a useless or invalid search command.

Solutions

1. Provide a valid non-empty header field name (e.g. "Subject", "From", custom X- headers).
2. Validate/trim the field name at the call site before constructing the query.
3. Fall back to a different search query type (e.g. SearchSubject) when no header name is available.

Example fix

// before
var query = new HeaderSearchQuery(headerName, searchText);
// after
var query = string.IsNullOrEmpty(headerName)
    ? SearchQuery.SubjectContains(searchText)
    : new HeaderSearchQuery(headerName, searchText);

if (string.IsNullOrEmpty(field))
    throw new ArgumentException("Header field name is required.", nameof(field));

bool IsValidHeaderField(string? field) => !string.IsNullOrWhiteSpace(field);

try
{
    var query = new HeaderSearchQuery(field, value);
}
catch (ArgumentException)
{
    query = SearchQuery.SubjectContains(value);
}

When it happens

Trigger: Calling new HeaderSearchQuery("", value) or HeaderSearchQuery.Contains("", text) with an empty field name.

Common situations: Building search queries from user input or configuration where the header name was read from an empty config value, a split string, or a variable that defaulted to string.Empty instead of null.

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

• The SearchOptions.All flag cannot be combined with a…
• array
• uri
• visitor
• bodyParts

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

Appendix: source

Thrown at MailKit/Search/HeaderSearchQuery.cs:60

		/// Creates a new header search query.
		/// </remarks>
		/// <param name="field">The header field name.</param>
		/// <param name="value">The value to match against.</param>
		/// <exception cref="System.ArgumentNullException">
		/// <para><paramref name="field"/> is <see langword="null" />.</para>
		/// <para>-or-</para>
		/// <para><paramref name="value"/> is <see langword="null" />.</para>
		/// </exception>
		/// <exception cref="System.ArgumentException">
		/// <paramref name="field"/> is empty.
		/// </exception>
		public HeaderSearchQuery (string field, string value) : base (SearchTerm.HeaderContains)
		{
			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 (value == null)
				throw new ArgumentNullException (nameof (value));

			Field = field;
			Value = value;
		}

		/// <summary>
		/// Gets the header field name.
		/// </summary>
		/// <remarks>
		/// Gets the header field name.
		/// </remarks>
		/// <value>The header field.</value>
		public string Field {
			get; private set;
		}

View on GitHub (pinned to 9d3859a785)