jstedfast/MailKit · error · MessageNotFoundException

The IMAP server did not return the requested body part…

Error message

The IMAP server did not return the requested body part headers.

What it means

MessageNotFoundException thrown by ProcessGetHeadersResponse (body-part overload) when the server's FETCH response lacks the requested BODY[part.HEADER] section. MailKit requested the specified body part's headers, but the server did not return them — usually because the message (and thus the part) no longer exists, or the part specifier no longer matches the message's structure.

Solutions

Catch MessageNotFoundException and handle the missing message/part gracefully (skip, log, re-sync).
Re-run GetBodyPart/GetBodyParts to obtain a fresh part specifier matching the current message structure.
Verify the message still exists by fetching its summary/flags before requesting part headers.

Example fix

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

// after
try {
    var headers = folder.GetHeaders(uid, cachedSpecifier);
} catch (MessageNotFoundException) {
    var body = folder.GetBodyPart(uid, "1"); // re-discover current structure
}

Defensive patterns

Strategy: try-catch

Validate before calling

var structure = folder.GetBodyParts(uid);
if (!structure.BodyParts.Any(p => p.PartSpecifier == specifier))
    throw new MessageNotFoundException($"Part {specifier} does not exist in current message structure.");

Try / catch

try { var headers = folder.GetHeaders(uid, partSpecifier); }
catch (MessageNotFoundException) { /* re-fetch BodyPart tree and retry once */ }

Prevention

Re-derive part specifiers from a fresh BodyStructure fetch rather than caching across sessions.
Verify the message still exists (summary fetch) before requesting part headers.
Handle MessageNotFoundException as an expected condition in shared-mailbox scenarios.

When it happens

Trigger: Calling ImapFolder.GetHeaders(UniqueId uid, string partSpecifier, ...) with a partSpecifier derived from an old BodyPart tree after the message changed or was expunged, or against a server that omits the section.

Common situations: Reusing cached BodyPart specifiers across sessions while server-side filters rewrote messages; message deleted by another client between GetBodyPart and GetHeaders; buggy/limited IMAP servers (e.g., some proxies) not returning the part.

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

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

Appendix: source

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

			CheckState (true, false);

			var command = string.Format ("UID FETCH {0} ({1})\r\n", uid, GetBodyPartQuery (partSpecifier, true, out tags));
			var ic = new ImapCommand (Engine, cancellationToken, this, command);
			ic.RegisterUntaggedHandler ("FETCH", FetchStreamHandler);
			ic.UserData = ctx = new FetchStreamContext (progress);

			Engine.QueueCommand (ic);

			return ic;
		}

		Stream ProcessGetHeadersResponse (ImapCommand ic, FetchStreamContext ctx, UniqueId uid, string[] tags)
		{
			ProcessFetchResponse (ic);

			if (!ctx.TryGetSection (uid, tags[0], out var section, true))
				throw new MessageNotFoundException ("The IMAP server did not return the requested body part headers.");

			return section.Stream;
		}

		/// <summary>
		/// Get the specified body part headers.
		/// </summary>
		/// <remarks>
		/// Gets the specified body part headers.
		/// </remarks>
		/// <returns>The body part headers.</returns>
		/// <param name="uid">The UID of the message.</param>
		/// <param name="partSpecifier">The body part specifier.</param>
		/// <param name="cancellationToken">The cancellation token.</param>
		/// <param name="progress">The progress reporting mechanism.</param>
		/// <exception cref="System.ArgumentNullException">
		/// <paramref name="partSpecifier"/> is <see langword="null" />.
		/// </exception>

View on GitHub (pinned to 9d3859a785)