jstedfast/MailKit · error · ArgumentOutOfRangeException

ArgumentOutOfRangeException

Error message

ArgumentOutOfRangeException

What it means

HeaderSet.Add(HeaderId) throws ArgumentOutOfRangeException when the header is HeaderId.Unknown, because Unknown is a sentinel, not a real header, and cannot be part of a header set. It also throws InvalidOperationException if the set is read-only.

Solutions

1. Verify the header resolves to a real HeaderId (not Unknown) before calling Add
2. Parse with HeaderId.FromHeaderName and check the result, adding the raw string overload Add(string) instead if the name is custom
3. Ensure enum variables are initialized to an actual HeaderId

Example fix

// before
var id = HeaderId.FromHeaderName (name);
set.Add (id); // throws if name unknown
// after
var id = HeaderId.FromHeaderName (name);
if (id == HeaderId.Unknown)
    set.Add (name); // keep custom header as string
else
    set.Add (id);

if (header == HeaderId.Unknown)
    throw new ArgumentException ("Header must be a known HeaderId", nameof (header));

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

try {
    set.Add (header);
} catch (ArgumentOutOfRangeException) {
    set.Add (rawHeaderName); // fall back to string form
}

When it happens

Trigger: Passing HeaderId.Unknown to Add(HeaderId); commonly the result of HeaderId.FromHeaderName on an unrecognized name.

Common situations: Parsing header names from config or user input where the name lookup falls back to Unknown; default-initialized enum variables; mapping untrusted strings to HeaderId.

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

• One or more of the headers is invalid.
• Specified argument was out of range of valid values…
• Specified argument was out of range of valid values…
• arrayIndex
• index

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

Appendix: source

Thrown at MailKit/HeaderSet.cs:203

		/// <summary>
		/// Add the specified header.
		/// </summary>
		/// <remarks>
		/// Adds the specified header to the set of headers.
		/// </remarks>
		/// <returns><see langword="true" /> if the header was added to the set; otherwise, <see langword="false" />.</returns>
		/// <param name="header">The header to add.</param>
		/// <exception cref="ArgumentOutOfRangeException">
		/// <paramref name="header"/> is not a valid <see cref="HeaderId"/>.
		/// </exception>
		/// <exception cref="InvalidOperationException">
		/// The operation is invalid because the <see cref="HeaderSet"/> is read-only.
		/// </exception>
		public bool Add (HeaderId header)
		{
			if (header == HeaderId.Unknown)
				throw new ArgumentOutOfRangeException (nameof (header));

			CheckReadOnly ();

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

		/// <summary>
		/// Add the specified header.
		/// </summary>
		/// <remarks>
		/// Adds the specified header to the set of headers.
		/// </remarks>
		/// <returns><see langword="true" /> if the header was added to the set; otherwise, <see langword="false" />.</returns>
		/// <param name="header">The header to add.</param>
		/// <exception cref="ArgumentNullException">
		/// <paramref name="header"/> is <see langword="null" />.
		/// </exception>
		/// <exception cref="InvalidOperationException">

View on GitHub (pinned to 9d3859a785)