jstedfast/MailKit · error · ArgumentException

Invalid unique identifier.

Error message

Invalid unique identifier.

What it means

UniqueIdSet.Add validates that the UniqueId being inserted is valid (Uid > 0). Passing a default/uninitialized UniqueId (whose Id is 0 or invalid) throws ArgumentException, because a unique identifier of 0 cannot be represented in an IMAP UID set.

Solutions

1. Check uid.IsValid (or uid.Id > 0) before calling Add and skip invalid entries.
2. Filter the source sequence with Where (uid => uid.IsValid) before AddRange.
3. Investigate why the invalid UniqueId was produced — typically a FETCH response without the UID item or fetch from a nonexistent folder.
4. If an invalid UID is legitimate for your flow, use a nullable representation (UniqueId?) instead of UniqueId.Invalid.

Example fix

// before
var set = new UniqueIdSet ();
foreach (var uid in fetchedUids)
    set.Add (uid); // throws on UniqueId.Invalid
// after
var set = new UniqueIdSet ();
foreach (var uid in fetchedUids.Where (uid => uid.IsValid))
    set.Add (uid);

if (uid.IsValid)
    set.Add (uid);
// or for batches:
var valid = fetchedUids.Where (u => u.IsValid).ToArray ();
set.AddRange (valid);

static bool IsValidUid (UniqueId uid) => uid.IsValid; // Id > 0

try {
    set.Add (uid);
} catch (ArgumentException ex) when (ex.ParamName == "uid") {
    logger.LogWarning ("Skipped invalid UniqueId (Id=0) from fetch response");
}

When it happens

Trigger: Calling UniqueIdSet.Add with a UniqueId created via default(UniqueId), new UniqueId(0), a UniqueId from a failed fetch, or UniqueId.Invalid; also via AddRange/enumerables containing such values, and in unit tests exercising argument validation.

Common situations: Parsing header/list results where the server omitted UID (yielding UniqueId.Zero), passing default-initialized structs from deserialization, copying UIDs from a different folder where validity checks were skipped, or building a set before checking uid.IsValid.

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

• Cannot search for an invalid unique identifier.
• Cannot rename a folder using itself as the new parent…
• Cannot search for an empty set of unique identifiers.
• count
• No indexes were specified.

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

Appendix: source

Thrown at MailKit/UniqueIdSet.cs:428

			}

			ranges.Add (new Range (uid, uid));
		}

		/// <summary>
		/// Adds the unique identifier to the set.
		/// </summary>
		/// <remarks>
		/// Adds the unique identifier to the set.
		/// </remarks>
		/// <param name="uid">The unique identifier to add.</param>
		/// <exception cref="System.ArgumentException">
		/// <paramref name="uid"/> is invalid.
		/// </exception>
		public void Add (UniqueId uid)
		{
			if (!uid.IsValid)
				throw new ArgumentException ("Invalid unique identifier.", nameof (uid));

			if (ranges.Count == 0) {
				ranges.Add (new Range (uid.Id, uid.Id));
				count++;
				return;
			}

			switch (SortOrder) {
			case SortOrder.Descending:
				BinaryInsertDescending (uid.Id);
				break;
			case SortOrder.Ascending:
				BinaryInsertAscending (uid.Id);
				break;
			default:
				Append (uid.Id);
				break;
			}

View on GitHub (pinned to 9d3859a785)