jstedfast/MailKit · error · ArgumentException

The number of messages and the number of flags must be…

Error message

The number of messages and the number of flags must be equal.

What it means

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.

Solutions

1. Make the counts match: derive flags from messages or filter both lists with the same predicate.
2. Use zip-style construction so each message is added together with its flag.
3. Assert counts are equal before calling Append to surface the producer bug earlier.

Example fix

// before
folder.Append(options, messages, flags);
// after
var paired = messages.Zip(flags, (m, f) => new { m, f }).Where(x => x.m != null).ToList();
folder.Append(options, paired.Select(x => x.m).ToList(), paired.Select(x => x.f).ToList());

if (messages.Count != flags.Count)
    throw new InvalidOperationException("messages/flags count mismatch");

bool CountsMatch<T,U>(IList<T> a, IList<U> b) => a.Count == b.Count;

try { folder.Append(options, messages, flags); } catch (ArgumentException ex) when (ex.Message.Contains("must be equal")) { /* rebuild paired lists */ }

When it happens

Trigger: Calling folder.Append(options, msgsOf3, flagsOf2) — any count mismatch, e.g. after filtering messages without filtering flags the same way.

Common situations: 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.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• ArgumentOutOfRangeException
• ArgumentNullException
• One or more of the messages is null.
• The uid is invalid.
• part

AI-assisted analysis of jstedfast/MailKit@9d3859a785 (2026-09-15). Data as JSON: /api/errors/7a817c5dc699f22d. Report an issue: GitHub.

Appendix: source

Thrown at MailKit/IMailFolderAppendExtensions.cs:949

		/// </exception>
		public static IList<UniqueId> Append (this IMailFolder folder, FormatOptions options, IList<MimeMessage> messages, IList<MessageFlags> flags, CancellationToken cancellationToken = default, ITransferProgress? progress = null)
		{
			if (options == null)
				throw new ArgumentNullException (nameof (options));

			if (messages == null)
				throw new ArgumentNullException (nameof (messages));

			for (int i = 0; i < messages.Count; i++) {
				if (messages[i] == null)
					throw new ArgumentException ("One or more of the messages is null.");
			}

			if (flags == null)
				throw new ArgumentNullException (nameof (flags));

			if (messages.Count != flags.Count)
				throw new ArgumentException ("The number of messages and the number of flags must be equal.");

			var requests = new AppendRequest[messages.Count];
			for (int i = 0; i < messages.Count; i++) {
				requests[i] = new AppendRequest (messages[i], flags[i]) {
					TransferProgress = progress
				};
			}

			return folder.Append (options, requests, cancellationToken);
		}

		/// <summary>
		/// Asynchronously append the specified messages to the folder.
		/// </summary>
		/// <remarks>
		/// Asynchronously appends the specified messages to the folder and returns the UniqueIds assigned to the messages.
		/// </remarks>
		/// <returns>The UIDs of the appended messages, if available; otherwise an empty array.</returns>

View on GitHub (pinned to 9d3859a785)