jstedfast/MailKit · error · ArgumentException

One or more of the headers is invalid.

Error message

One or more of the headers is invalid.

What it means

HeaderSet.AddRange(IEnumerable<HeaderId>) throws ArgumentException("One or more of the headers is invalid.") when any element in the collection equals HeaderId.Unknown. Unknown is a placeholder, not a real header.

Solutions

1. Filter out HeaderId.Unknown before AddRange: headers.Where (h => h != HeaderId.Unknown)
2. Fall back to the string-based AddRange for names that don't map to a HeaderId
3. Validate the collection elements before the call

Example fix

// before
set.AddRange (parsedIds); // may contain HeaderId.Unknown
// after
set.AddRange (parsedIds.Where (id => id != HeaderId.Unknown));

var valid = headers.Where (h => h != HeaderId.Unknown);
set.AddRange (valid);

static bool IsUsableHeader (HeaderId id) => id != HeaderId.Unknown;

try {
    set.AddRange (headers);
} catch (ArgumentException ex) {
    set.AddRange (headers.Where (h => h != HeaderId.Unknown));
}

When it happens

Trigger: Passing collections containing HeaderId.Unknown, typically produced by HeaderId.FromHeaderName on unrecognized names.

Common situations: Bulk-adding parsed header names where some didn't map to known HeaderId values; default enum values in structs/lists.

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

• ArgumentOutOfRangeException
• The header field is invalid.
• ArgumentOutOfRangeException
• ArgumentNullException
• ArgumentNullException

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

Appendix: source

Thrown at MailKit/HeaderSet.cs:280

		/// <exception cref="ArgumentNullException">
		/// <paramref name="headers"/> is <see langword="null" />.
		/// </exception>
		/// <exception cref="ArgumentException">
		/// One or more of the specified <paramref name="headers"/> is invalid.
		/// </exception>
		/// <exception cref="InvalidOperationException">
		/// The operation is invalid because the <see cref="HeaderSet"/> is read-only.
		/// </exception>
		public void AddRange (IEnumerable<HeaderId> headers)
		{
			if (headers == null)
				throw new ArgumentNullException (nameof (headers));

			CheckReadOnly ();

			foreach (var header in headers) {
				if (header == HeaderId.Unknown)
					throw new ArgumentException ("One or more of the headers is invalid.", nameof (headers));

				hash.Add (header.ToHeaderName ().ToUpperInvariant ());
			}
		}

		/// <summary>
		/// Add a collection of headers.
		/// </summary>
		/// <remarks>
		/// Adds the specified headers to the set of headers.
		/// </remarks>
		/// <param name="headers">The headers to add.</param>
		/// <exception cref="ArgumentNullException">
		/// <paramref name="headers"/> is <see langword="null" />.
		/// </exception>
		/// <exception cref="ArgumentException">
		/// One or more of the specified <paramref name="headers"/> is invalid.
		/// </exception>

View on GitHub (pinned to 9d3859a785)