{"record":{"id":"7a817c5dc699f22d","repo":"jstedfast/MailKit","slug":"the-number-of-messages-and-the-number-of-flags-must-be-equal","errorCode":null,"errorMessage":"The number of messages and the number of flags must be equal.","messagePattern":"The number of messages and the number of flags must be equal\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"MailKit/IMailFolderAppendExtensions.cs","lineNumber":949,"sourceCode":"\t\t/// </exception>\n\t\tpublic static IList<UniqueId> Append (this IMailFolder folder, FormatOptions options, IList<MimeMessage> messages, IList<MessageFlags> flags, CancellationToken cancellationToken = default, ITransferProgress? progress = null)\n\t\t{\n\t\t\tif (options == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (options));\n\n\t\t\tif (messages == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (messages));\n\n\t\t\tfor (int i = 0; i < messages.Count; i++) {\n\t\t\t\tif (messages[i] == null)\n\t\t\t\t\tthrow new ArgumentException (\"One or more of the messages is null.\");\n\t\t\t}\n\n\t\t\tif (flags == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (flags));\n\n\t\t\tif (messages.Count != flags.Count)\n\t\t\t\tthrow new ArgumentException (\"The number of messages and the number of flags must be equal.\");\n\n\t\t\tvar requests = new AppendRequest[messages.Count];\n\t\t\tfor (int i = 0; i < messages.Count; i++) {\n\t\t\t\trequests[i] = new AppendRequest (messages[i], flags[i]) {\n\t\t\t\t\tTransferProgress = progress\n\t\t\t\t};\n\t\t\t}\n\n\t\t\treturn folder.Append (options, requests, cancellationToken);\n\t\t}\n\n\t\t/// <summary>\n\t\t/// Asynchronously append the specified messages to the folder.\n\t\t/// </summary>\n\t\t/// <remarks>\n\t\t/// Asynchronously appends the specified messages to the folder and returns the UniqueIds assigned to the messages.\n\t\t/// </remarks>\n\t\t/// <returns>The UIDs of the appended messages, if available; otherwise an empty array.</returns>","sourceCodeStart":931,"sourceCodeEnd":967,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/IMailFolderAppendExtensions.cs#L931-L967","documentation":"Append builds a one-to-one mapping between messages and their flags, so it throws ArgumentException (\"The number of messages and the number of flags must be equal.\") when messages.Count != flags.Count. This is a pre-flight pairing validation before any IMAP command is issued.","triggerScenarios":"Calling folder.Append(options, msgsOf3, flagsOf2) — any count mismatch, e.g. after filtering messages without filtering flags the same way.","commonSituations":"Filtering null/invalid messages from one list but not the other; batching logic that splits messages into chunks but reuses a single flags list; merging lists from two sources.","solutions":["Make the counts match: derive flags from messages or filter both lists with the same predicate.","Use zip-style construction so each message is added together with its flag.","Assert counts are equal before calling Append to surface the producer bug earlier."],"exampleFix":"// before\nfolder.Append(options, messages, flags);\n// after\nvar paired = messages.Zip(flags, (m, f) => new { m, f }).Where(x => x.m != null).ToList();\nfolder.Append(options, paired.Select(x => x.m).ToList(), paired.Select(x => x.f).ToList());","handlingStrategy":"validation","validationCode":"if (messages.Count != flags.Count)\n    throw new InvalidOperationException(\"messages/flags count mismatch\");","typeGuard":"bool CountsMatch<T,U>(IList<T> a, IList<U> b) => a.Count == b.Count;","tryCatchPattern":"try { folder.Append(options, messages, flags); } catch (ArgumentException ex) when (ex.Message.Contains(\"must be equal\")) { /* rebuild paired lists */ }","preventionTips":["Always derive flags from the same filtered source as messages","Pair messages and flags with Zip before batching","Chunk both lists together, never independently"],"tags":["count-mismatch","mailkit","csharp","argument-validation"],"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-16T04:17:20.429Z"}