{"record":{"id":"920ff45d8dd1f513","repo":"jstedfast/MailKit","slug":"the-header-field-is-invalid","errorCode":null,"errorMessage":"The header field is invalid.","messagePattern":"The header field is invalid\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"MailKit/HeaderSet.cs","lineNumber":230,"sourceCode":"\t\t/// </summary>\n\t\t/// <remarks>\n\t\t/// Adds the specified header to the set of headers.\n\t\t/// </remarks>\n\t\t/// <returns><see langword=\"true\" /> if the header was added to the set; otherwise, <see langword=\"false\" />.</returns>\n\t\t/// <param name=\"header\">The header to add.</param>\n\t\t/// <exception cref=\"ArgumentNullException\">\n\t\t/// <paramref name=\"header\"/> is <see langword=\"null\" />.\n\t\t/// </exception>\n\t\t/// <exception cref=\"InvalidOperationException\">\n\t\t/// The operation is invalid because the <see cref=\"HeaderSet\"/> is read-only.\n\t\t/// </exception>\n\t\tpublic bool Add (string header)\n\t\t{\n\t\t\tif (header == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (header));\n\n\t\t\tif (!IsValid (header))\n\t\t\t\tthrow new ArgumentException (\"The header field is invalid.\", nameof (header));\n\n\t\t\tCheckReadOnly ();\n\n\t\t\treturn hash.Add (header.ToUpperInvariant ());\n\t\t}\n\n\t\t/// <summary>\n\t\t/// Add the specified header.\n\t\t/// </summary>\n\t\t/// <remarks>\n\t\t/// Adds the specified header to the set of headers.\n\t\t/// </remarks>\n\t\t/// <param name=\"item\">The header to add.</param>\n\t\t/// <exception cref=\"ArgumentNullException\">\n\t\t/// <paramref name=\"item\"/> is <see langword=\"null\" />.\n\t\t/// </exception>\n\t\t/// <exception cref=\"InvalidOperationException\">\n\t\t/// The operation is invalid because the <see cref=\"HeaderSet\"/> is read-only.","sourceCodeStart":212,"sourceCodeEnd":248,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/HeaderSet.cs#L212-L248","documentation":"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).","triggerScenarios":"Adding strings with invalid characters (':', spaces, non-token chars), empty strings if rejected by IsValid, or typo'd header names with illegal characters.","commonSituations":"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.","solutions":["Pass only the header field name, trimmed, with no colon or value","Sanitize the name (trim whitespace, remove illegal characters) or map it to a known HeaderId and use Add(HeaderId)","Validate the string against header-name token rules before calling Add"],"exampleFix":"// before\nset.Add (\"Subject: important\"); // invalid\n// after\nset.Add (HeaderId.Subject);\nset.Add (\"X-Custom-Important\");","handlingStrategy":"validation","validationCode":"bool ok = !string.IsNullOrEmpty (header) &&\n          header.IndexOf (':') < 0 &&\n          !header.Any (c => char.IsControl (c) || c == ' ');","typeGuard":"static bool LooksLikeHeaderName (string s) =>\n    !string.IsNullOrEmpty (s) && s.All (c => !char.IsWhiteSpace (c) && c != ':' && !char.IsControl (c));","tryCatchPattern":"try {\n    set.Add (header);\n} catch (ArgumentException ex) {\n    logger.LogWarning (\"Rejected invalid header name '{Name}': {Msg}\", header, ex.Message);\n}","preventionTips":["Pass only the bare header name (no colon or value)","Trim whitespace from names from config/user input","Prefer HeaderId enum values for well-known headers"],"tags":["csharp","mailkit","argument","validation"],"backgroundTag":"invalid-argument-format","analyzedSha":"9d3859a7855e3e17582c07fd01972b8e262bf176","analyzedAt":"2026-09-15T15:46:11.592Z","contentChangedAt":"2026-09-15T15:46:11.592Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}