jstedfast/MailKit · error · ArgumentException

The header field is invalid.

Error message

The header field is invalid.

What it means

HeaderSet.Add(string) validates the header name with IsValid and throws ArgumentException("The header field is invalid.") when the string is not a syntactically valid header field name (e.g. contains spaces, colons, or control characters).

Solutions

1. Pass only the header field name, trimmed, with no colon or value
2. Sanitize the name (trim whitespace, remove illegal characters) or map it to a known HeaderId and use Add(HeaderId)
3. Validate the string against header-name token rules before calling Add

Example fix

// before
set.Add ("Subject: important"); // invalid
// after
set.Add (HeaderId.Subject);
set.Add ("X-Custom-Important");

bool ok = !string.IsNullOrEmpty (header) &&
          header.IndexOf (':') < 0 &&
          !header.Any (c => char.IsControl (c) || c == ' ');

static bool LooksLikeHeaderName (string s) =>
    !string.IsNullOrEmpty (s) && s.All (c => !char.IsWhiteSpace (c) && c != ':' && !char.IsControl (c));

try {
    set.Add (header);
} catch (ArgumentException ex) {
    logger.LogWarning ("Rejected invalid header name '{Name}': {Msg}", header, ex.Message);
}

When it happens

Trigger: Adding strings with invalid characters (':', spaces, non-token chars), empty strings if rejected by IsValid, or typo'd header names with illegal characters.

Common situations: Header names read from user input or config; concatenating name+value into one string ("Subject: foo") instead of passing just the name; localized or whitespace-padded names.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• One or more of the headers is invalid.
• The language code cannot be empty.
• ArgumentOutOfRangeException
• ArgumentNullException
• ArgumentNullException

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

Appendix: source

Thrown at MailKit/HeaderSet.cs:230

		/// </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">
		/// The operation is invalid because the <see cref="HeaderSet"/> is read-only.
		/// </exception>
		public bool Add (string header)
		{
			if (header == null)
				throw new ArgumentNullException (nameof (header));

			if (!IsValid (header))
				throw new ArgumentException ("The header field is invalid.", nameof (header));

			CheckReadOnly ();

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

		/// <summary>
		/// Add the specified header.
		/// </summary>
		/// <remarks>
		/// Adds the specified header to the set of headers.
		/// </remarks>
		/// <param name="item">The header to add.</param>
		/// <exception cref="ArgumentNullException">
		/// <paramref name="item"/> is <see langword="null" />.
		/// </exception>
		/// <exception cref="InvalidOperationException">
		/// The operation is invalid because the <see cref="HeaderSet"/> is read-only.

View on GitHub (pinned to 9d3859a785)