{"record":{"id":"39dd661f48515c17","repo":"jstedfast/MailKit","slug":"the-uid-is-invalid-imapfolderfetch","errorCode":null,"errorMessage":"The uid is invalid.","messagePattern":"The uid is invalid\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolderFetch.cs","lineNumber":2523,"sourceCode":"\t\t\t} else if (partSpec.Length > 0) {\n\t\t\t\ttags = new string[] {\n\t\t\t\t\tpartSpec + \".MIME\",\n\t\t\t\t\tpartSpec\n\t\t\t\t};\n\n\t\t\t\tquery = string.Format (\"BODY.PEEK[{0}] BODY.PEEK[{1}]\", tags[0], tags[1]);\n\t\t\t} else {\n\t\t\t\ttags = new string[] { string.Empty };\n\t\t\t\tquery = \"BODY.PEEK[]\";\n\t\t\t}\n\n\t\t\treturn query;\n\t\t}\n\n\t\tImapCommand QueueGetHeadersCommand (UniqueId uid, CancellationToken cancellationToken, ITransferProgress? progress, out FetchStreamContext ctx)\n\t\t{\n\t\t\tif (!uid.IsValid)\n\t\t\t\tthrow new ArgumentException (\"The uid is invalid.\", nameof (uid));\n\n\t\t\tCheckState (true, false);\n\n\t\t\tvar ic = new ImapCommand (Engine, cancellationToken, this, \"UID FETCH %u (BODY.PEEK[HEADER])\\r\\n\", uid.Id);\n\t\t\tic.RegisterUntaggedHandler (\"FETCH\", FetchStreamHandler);\n\t\t\tic.UserData = ctx = new FetchStreamContext (progress);\n\n\t\t\tEngine.QueueCommand (ic);\n\n\t\t\treturn ic;\n\t\t}\n\n\t\tStream ProcessGetHeadersResponse (ImapCommand ic, FetchStreamContext ctx, UniqueId uid)\n\t\t{\n\t\t\tProcessFetchResponse (ic);\n\n\t\t\tif (!ctx.TryGetSection (uid, \"HEADER\", out var section, true))\n\t\t\t\tthrow new MessageNotFoundException (\"The IMAP server did not return the requested message headers.\");","sourceCodeStart":2505,"sourceCodeEnd":2541,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolderFetch.cs#L2505-L2541","documentation":"MailKit throws this ArgumentException from QueueGetHeadersCommand when GetHeaders/GetHeadersAsync is called with a UniqueId whose IsValid is false (UniqueId.Zero or default). The IMAP UID FETCH command cannot be issued without a valid numeric UID, so the library fails fast with a descriptive message naming the `uid` parameter. This is a caller-side input validation error, not a server problem.","triggerScenarios":"Calling ImapFolder.GetHeaders(UniqueId uid, ...) or the async variant with UniqueId.Zero, an uninitialized/default UniqueId, or a UniqueId from a failed/expired UIDVALIDITY mapping.","commonSituations":"Storing UIDs across sessions and reusing them after the folder's UIDVALIDITY changed; constructing `new UniqueId()` instead of fetching real UIDs from a search; a prior Search/Fetch returning UniqueId.Zero for folders that don't support UIDs.","solutions":["Check `uid.IsValid` before calling GetHeaders and skip or re-fetch the message if false.","Re-run a Search/Fetch to obtain fresh UIDs, since UIDVALIDITY may have changed (old UIDs are invalid).","If you only have a sequence index, use the GetHeaders(int index, ...) overload instead."],"exampleFix":"// before\nvar headers = folder.GetHeaders(storedUid);\n\n// after\nif (!storedUid.IsValid)\n    storedUid = folder.Search(SearchQuery.Subject.Contains(\"report\")).FirstOrDefault();\nvar headers = folder.GetHeaders(storedUid);","handlingStrategy":"validation","validationCode":"if (uid == default || !uid.IsValid)\n    throw new InvalidOperationException(\"UID must be obtained from a Search/Fetch on this folder before calling GetHeaders.\");","typeGuard":"bool IsValidUid(UniqueId uid) => uid is { IsValid: true, Id: > 0 };","tryCatchPattern":"try { var headers = folder.GetHeaders(uid); }\ncatch (ArgumentException ex) when (ex.ParamName == \"uid\") { /* re-acquire UID via Search */ }","preventionTips":["Never persist UIDs without also persisting the folder's UIDValidity.","Always obtain UniqueId values from Search/Fetch results, never construct them manually.","Check uid.IsValid at API boundaries before any UID-based IMAP call."],"tags":["imap","argument-validation","mailkit","uid"],"backgroundTag":"invalid-argument-value","analyzedSha":"9d3859a7855e3e17582c07fd01972b8e262bf176","analyzedAt":"2026-09-15T15:46:11.592Z","contentChangedAt":"2026-09-15T15:46:11.592Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}