jstedfast/MailKit · error · ArgumentException

The uid is invalid.

Error message

The uid is invalid.

What it means

MailKit throws this ArgumentException from QueueGetHeadersCommand when GetHeaders/GetHeadersAsync is called with a UniqueId whose IsValid is false (UniqueId.Zero or default). The IMAP UID FETCH command cannot be issued without a valid numeric UID, so the library fails fast with a descriptive message naming the `uid` parameter. This is a caller-side input validation error, not a server problem.

Solutions

1. Check `uid.IsValid` before calling GetHeaders and skip or re-fetch the message if false.
2. Re-run a Search/Fetch to obtain fresh UIDs, since UIDVALIDITY may have changed (old UIDs are invalid).
3. If you only have a sequence index, use the GetHeaders(int index, ...) overload instead.

Example fix

// before
var headers = folder.GetHeaders(storedUid);

// after
if (!storedUid.IsValid)
    storedUid = folder.Search(SearchQuery.Subject.Contains("report")).FirstOrDefault();
var headers = folder.GetHeaders(storedUid);

if (uid == default || !uid.IsValid)
    throw new InvalidOperationException("UID must be obtained from a Search/Fetch on this folder before calling GetHeaders.");

bool IsValidUid(UniqueId uid) => uid is { IsValid: true, Id: > 0 };

try { var headers = folder.GetHeaders(uid); }
catch (ArgumentException ex) when (ex.ParamName == "uid") { /* re-acquire UID via Search */ }

When it happens

Trigger: Calling ImapFolder.GetHeaders(UniqueId uid, ...) or the async variant with UniqueId.Zero, an uninitialized/default UniqueId, or a UniqueId from a failed/expired UIDVALIDITY mapping.

Common situations: Storing UIDs across sessions and reusing them after the folder's UIDVALIDITY changed; constructing `new UniqueId()` instead of fetching real UIDs from a search; a prior Search/Fetch returning UniqueId.Zero for folders that don't support UIDs.

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

• The uid is invalid.
• offset
• count
• The destination folder does not belong to this ImapClient.
• The name is not a legal folder name.

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

Appendix: source

Thrown at MailKit/Net/Imap/ImapFolderFetch.cs:2523

			} else if (partSpec.Length > 0) {
				tags = new string[] {
					partSpec + ".MIME",
					partSpec
				};

				query = string.Format ("BODY.PEEK[{0}] BODY.PEEK[{1}]", tags[0], tags[1]);
			} else {
				tags = new string[] { string.Empty };
				query = "BODY.PEEK[]";
			}

			return query;
		}

		ImapCommand QueueGetHeadersCommand (UniqueId uid, CancellationToken cancellationToken, ITransferProgress? progress, out FetchStreamContext ctx)
		{
			if (!uid.IsValid)
				throw new ArgumentException ("The uid is invalid.", nameof (uid));

			CheckState (true, false);

			var ic = new ImapCommand (Engine, cancellationToken, this, "UID FETCH %u (BODY.PEEK[HEADER])\r\n", uid.Id);
			ic.RegisterUntaggedHandler ("FETCH", FetchStreamHandler);
			ic.UserData = ctx = new FetchStreamContext (progress);

			Engine.QueueCommand (ic);

			return ic;
		}

		Stream ProcessGetHeadersResponse (ImapCommand ic, FetchStreamContext ctx, UniqueId uid)
		{
			ProcessFetchResponse (ic);

			if (!ctx.TryGetSection (uid, "HEADER", out var section, true))
				throw new MessageNotFoundException ("The IMAP server did not return the requested message headers.");

View on GitHub (pinned to 9d3859a785)