jstedfast/MailKit · error · MessageNotFoundException

The IMAP server did not return the requested message…

Error message

The IMAP server did not return the requested message headers.

What it means

MessageNotFoundException thrown by ProcessGetHeadersResponse when the IMAP server's FETCH response did not include a BODY[HEADER] section for the requested UID. MailKit queued a UID FETCH (BODY.PEEK[HEADER]) command, but no matching section arrived — typically because the message no longer exists on the server. It signals the requested data is unobtainable rather than a bad argument.

Solutions

1. Catch MessageNotFoundException and treat the message as deleted; skip it and continue.
2. Re-fetch the folder summary/Search to get a current message list, then retry with a valid UID.
3. Check the folder's UIDValidity; if it changed, invalidate all cached UIDs and re-enumerate messages.

Example fix

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

// after
HeaderList headers;
try {
    headers = folder.GetHeaders(uid);
} catch (MessageNotFoundException) {
    continue; // message was deleted server-side
}

var summary = folder.Fetch(new[] { uid.Id }, MessageSummaryItems.UniqueId, cancellationToken: ct);
if (summary.Length == 0) throw new MessageNotFoundException("Message no longer exists on the server.");

try { var headers = folder.GetHeaders(uid); }
catch (MessageNotFoundException) { /* treat as deleted: remove from local cache and skip */ }

When it happens

Trigger: Calling ImapFolder.GetHeaders(UniqueId uid, ...) (or async) for a message that was expunged concurrently, on a server that silently omits the section, or after the message set changed between the search and the fetch.

Common situations: Another client or auto-expunge deleted the message between your Search and GetHeaders calls; server-side junk cleanup removed messages mid-session; UIDVALIDITY changed and the UID maps to a nonexistent message.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• The IMAP server did not return the requested stream.
• The IMAP server did not return the requested body part…
• The IMAP server did not return the requested message.
• The IMAP server did not return the requested body part.
• Value cannot be null. (Parameter 'name')

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

Appendix: source

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

				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.");

			return section.Stream;
		}

		/// <summary>
		/// Get the specified message headers.
		/// </summary>
		/// <remarks>
		/// Gets the specified message headers.
		/// </remarks>
		/// <returns>The message headers.</returns>
		/// <param name="uid">The UID of the message.</param>
		/// <param name="cancellationToken">The cancellation token.</param>
		/// <param name="progress">The progress reporting mechanism.</param>
		/// <exception cref="System.ArgumentException">
		/// <paramref name="uid"/> is invalid.
		/// </exception>
		/// <exception cref="System.ObjectDisposedException">

View on GitHub (pinned to 9d3859a785)