jstedfast/MailKit · error · ArgumentException

The uid is invalid. (Parameter 'uid')

Error message

The uid is invalid. (Parameter 'uid')

What it means

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.

Solutions

1. Only pass UniqueId values obtained from this folder's current session (check uid.IsValid first)
2. Re-fetch message uids if the folder was re-opened or UIDVALIDITY changed
3. Guard the call with if (uid.IsValid) before calling Replace
4. Wrap in try/catch (ArgumentException) and refresh your uid cache

Example fix

// before
var uid = cachedUid; // possibly default
folder.Replace(FormatOptions.Default, uid, request);
// after
if (!cachedUid.IsValid)
    cachedUid = folder.Fetch(...) /* re-acquire */;
folder.Replace(FormatOptions.Default, cachedUid, request);

if (!uid.IsValid) throw new InvalidOperationException($"Invalid uid {uid}");

bool IsUsableUid(UniqueId uid) => uid.IsValid;

try { folder.Replace(FormatOptions.Default, uid, request); }
catch (ArgumentException ex) { log.LogError(ex, "Invalid uid; refreshing cache"); RefreshUidCache(); }

When it happens

Trigger: Calling Replace with a default-constructed UniqueId, a UniqueId from a different folder/client after the folder was recycled, or deserialized/zero-valued uids.

Common situations: Caching uids across IMAP sessions (uids can change if UIDVALIDITY changes); using UniqueId.Zero or default; mixing message-index with uid values.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Cannot search for an invalid unique identifier.
• Invalid unique identifier.
• All folders must be ImapFolders.
• Annotation entry paths must not end with '/'.
• Annotation entry paths must not end with '.'.

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

Appendix: source

Thrown at MailKit/Net/Imap/ImapFolder.cs:4858

				if (uids != null && uid.HasValue)
					uids.Add (uid.Value);
				else
					uids = null;
			}

			if (uids == null)
				return Array.Empty<UniqueId> ();

			return uids;
		}

		void ValidateArguments (FormatOptions options, UniqueId uid, IReplaceRequest request)
		{
			if (options == null)
				throw new ArgumentNullException (nameof (options));

			if (!uid.IsValid)
				throw new ArgumentException ("The uid is invalid.", nameof (uid));

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

			if (request.Destination != null && !(request.Destination is ImapFolder target && target.Engine == Engine))
				throw new ArgumentException ("The destination folder does not belong to this ImapClient.", nameof (request));

			if (request.Annotations != null && request.Annotations.Count > 0 && (Engine.Capabilities & ImapCapabilities.Annotate) == 0)
				throw new NotSupportedException ("The IMAP server does not support annotations.");

			CheckState (true, true);
		}

		ImapCommand QueueReplaceCommand (FormatOptions options, UniqueId uid, IReplaceRequest request, CancellationToken cancellationToken)
		{
			var format = CreateAppendOptions (options);
			int numKeywords = request.Keywords != null ? request.Keywords.Count : 0;
			var builder = new StringBuilder ($"UID REPLACE {uid} %F ");

View on GitHub (pinned to 9d3859a785)