{"record":{"id":"b8838a72ca87f6aa","repo":"jstedfast/MailKit","slug":"the-uid-is-invalid-parameter-uid","errorCode":null,"errorMessage":"The uid is invalid. (Parameter 'uid')","messagePattern":"The uid is invalid\\. \\(Parameter 'uid'\\)","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolder.cs","lineNumber":4858,"sourceCode":"\t\t\t\tif (uids != null && uid.HasValue)\n\t\t\t\t\tuids.Add (uid.Value);\n\t\t\t\telse\n\t\t\t\t\tuids = null;\n\t\t\t}\n\n\t\t\tif (uids == null)\n\t\t\t\treturn Array.Empty<UniqueId> ();\n\n\t\t\treturn uids;\n\t\t}\n\n\t\tvoid ValidateArguments (FormatOptions options, UniqueId uid, IReplaceRequest request)\n\t\t{\n\t\t\tif (options == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (options));\n\n\t\t\tif (!uid.IsValid)\n\t\t\t\tthrow new ArgumentException (\"The uid is invalid.\", nameof (uid));\n\n\t\t\tif (request == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (request));\n\n\t\t\tif (request.Destination != null && !(request.Destination is ImapFolder target && target.Engine == Engine))\n\t\t\t\tthrow new ArgumentException (\"The destination folder does not belong to this ImapClient.\", nameof (request));\n\n\t\t\tif (request.Annotations != null && request.Annotations.Count > 0 && (Engine.Capabilities & ImapCapabilities.Annotate) == 0)\n\t\t\t\tthrow new NotSupportedException (\"The IMAP server does not support annotations.\");\n\n\t\t\tCheckState (true, true);\n\t\t}\n\n\t\tImapCommand QueueReplaceCommand (FormatOptions options, UniqueId uid, IReplaceRequest request, CancellationToken cancellationToken)\n\t\t{\n\t\t\tvar format = CreateAppendOptions (options);\n\t\t\tint numKeywords = request.Keywords != null ? request.Keywords.Count : 0;\n\t\t\tvar builder = new StringBuilder ($\"UID REPLACE {uid} %F \");","sourceCodeStart":4840,"sourceCodeEnd":4876,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolder.cs#L4840-L4876","documentation":"Replace by UID validates that the supplied UniqueId is valid (Uid > 0 andValidity flag). A default(UniqueId) or an id from an invalid source fails UniqueId.IsValid and throws ArgumentException. UIDs are only meaningful within the folder that produced them.","triggerScenarios":"Calling Replace with a default-constructed UniqueId, a UniqueId from a different folder/client after the folder was recycled, or deserialized/zero-valued uids.","commonSituations":"Caching uids across IMAP sessions (uids can change if UIDVALIDITY changes); using UniqueId.Zero or default; mixing message-index with uid values.","solutions":["Only pass UniqueId values obtained from this folder's current session (check uid.IsValid first)","Re-fetch message uids if the folder was re-opened or UIDVALIDITY changed","Guard the call with if (uid.IsValid) before calling Replace","Wrap in try/catch (ArgumentException) and refresh your uid cache"],"exampleFix":"// before\nvar uid = cachedUid; // possibly default\nfolder.Replace(FormatOptions.Default, uid, request);\n// after\nif (!cachedUid.IsValid)\n    cachedUid = folder.Fetch(...) /* re-acquire */;\nfolder.Replace(FormatOptions.Default, cachedUid, request);","handlingStrategy":"validation","validationCode":"if (!uid.IsValid) throw new InvalidOperationException($\"Invalid uid {uid}\");","typeGuard":"bool IsUsableUid(UniqueId uid) => uid.IsValid;","tryCatchPattern":"try { folder.Replace(FormatOptions.Default, uid, request); }\ncatch (ArgumentException ex) { log.LogError(ex, \"Invalid uid; refreshing cache\"); RefreshUidCache(); }","preventionTips":["Cache uids only within a session and validate UIDVALIDITY","Never persist raw uid values across reconnects without revalidation","Distinguish message indices from uids in your data model"],"tags":["imap","uniqueid","argument-validation","invalid-uid"],"backgroundTag":"invalid-identifier-format","analyzedSha":"9d3859a7855e3e17582c07fd01972b8e262bf176","analyzedAt":"2026-09-15T15:46:11.592Z","contentChangedAt":"2026-09-15T15:46:11.592Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}