{"record":{"id":"0b4f541408cda151","repo":"jstedfast/MailKit","slug":"cannot-search-an-empty-header-field-name-searchquery","errorCode":null,"errorMessage":"Cannot search an empty header field name.","messagePattern":"Cannot search an empty header field name\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"MailKit/Search/SearchQuery.cs","lineNumber":675,"sourceCode":"\t\t/// </remarks>\n\t\t/// <returns>A <see cref=\"HeaderSearchQuery\"/>.</returns>\n\t\t/// <param name=\"field\">The header field to match against.</param>\n\t\t/// <param name=\"text\">The text to match against.</param>\n\t\t/// <exception cref=\"System.ArgumentNullException\">\n\t\t/// <para><paramref name=\"field\"/> is <see langword=\"null\" />.</para>\n\t\t/// <para>-or-</para>\n\t\t/// <para><paramref name=\"text\"/> is <see langword=\"null\" />.</para>\n\t\t/// </exception>\n\t\t/// <exception cref=\"System.ArgumentException\">\n\t\t/// <paramref name=\"field\"/> is empty.\n\t\t/// </exception>\n\t\tpublic static HeaderSearchQuery HeaderContains (string field, string text)\n\t\t{\n\t\t\tif (field == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (field));\n\n\t\t\tif (field.Length == 0)\n\t\t\t\tthrow new ArgumentException (\"Cannot search an empty header field name.\", nameof (field));\n\n\t\t\tif (text == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (text));\n\n\t\t\treturn new HeaderSearchQuery (field, text);\n\t\t}\n\n\t\t/// <summary>\n\t\t/// Match messages that are larger than the specified number of octets.\n\t\t/// </summary>\n\t\t/// <remarks>\n\t\t/// <para>Matches messages that are larger than the specified number of octets.</para>\n\t\t/// <note type=\"note\">This is equivalent to the <c>LARGER</c> search key as defined in <a href=\"https://datatracker.ietf.org/doc/html/rfc3501#section-6.4.4\">rfc3501</a>.</note>\n\t\t/// </remarks>\n\t\t/// <returns>A <see cref=\"NumericSearchQuery\"/>.</returns>\n\t\t/// <param name=\"octets\">The number of octets.</param>\n\t\t/// <exception cref=\"System.ArgumentOutOfRangeException\">\n\t\t/// <paramref name=\"octets\"/> is a negative value.","sourceCodeStart":657,"sourceCodeEnd":693,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Search/SearchQuery.cs#L657-L693","documentation":"SearchQuery.HeaderContains rejects an empty (zero-length) header field name with ArgumentException, because an IMAP HEADER search term needs a concrete header field (e.g. \"Subject\", \"From\"). An empty name would produce a meaningless or server-rejected search command, so MailKit fails fast.","triggerScenarios":"Calling SearchQuery.HeaderContains(\"\", \"text\") — commonly the result of trimming user input to nothing, or a split of \"field:value\" strings where the field part is empty (e.g. \":value\").","commonSituations":"Users entering \":something\" or just spaces in a filter box; parsing header filters from strings like \"=value\"; blank form fields submitted for the header name.","solutions":["Validate the field name with string.IsNullOrWhiteSpace before calling HeaderContains and surface a UI/config error instead.","Trim user-supplied header names and reject empties at input time.","Use a default header (e.g. \"Subject\") when no field is specified, if that matches your semantics."],"exampleFix":"// before\nvar query = SearchQuery.HeaderContains(inputField, inputText);\n// after\nvar field = inputField?.Trim();\nif (string.IsNullOrEmpty(field))\n    throw new ArgumentException(\"Header field name is required.\");\nvar query = SearchQuery.HeaderContains(field, inputText);","handlingStrategy":"validation","validationCode":"var field = inputField?.Trim();\nif (string.IsNullOrEmpty(field))\n    return null; // or report a user-facing validation error\nvar query = SearchQuery.HeaderContains(field, text);","typeGuard":"static bool IsValidHeaderName(string field) =>\n    !string.IsNullOrWhiteSpace(field);","tryCatchPattern":"try {\n    query = SearchQuery.HeaderContains(field, text);\n} catch (ArgumentException ex) when (ex.ParamName == nameof(field)) {\n    userErrors.Add(\"Header field name cannot be empty.\");\n    query = null;\n}","preventionTips":["Trim and reject empty header names at UI/input validation time.","Reject 'field:value' style strings whose field part is empty.","Add a validation rule to the search-request model for header names."],"tags":["argument-validation","imap-search","empty-string","mailkit"],"backgroundTag":"empty-required-field","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"}