{"record":{"id":"a288740f2eb2a425","repo":"jstedfast/MailKit","slug":"the-partial-extension-only-supports-uid-based-fetch-requests","errorCode":null,"errorMessage":"The PARTIAL extension only supports UID-based FETCH requests.","messagePattern":"The PARTIAL extension only supports UID-based FETCH requests\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"MailKit/Net/Imap/ImapFolderFetch.cs","lineNumber":1358,"sourceCode":"\t\t\tif (previewText)\n\t\t\t\tawait GetPreviewTextAsync (ctx, cancellationToken).ConfigureAwait (false);\n\n\t\t\treturn ctx.Messages.AsReadOnly ();\n\t\t}\n\n\t\tbool CheckCanFetch (IList<int> indexes, IFetchRequest request)\n\t\t{\n\t\t\tif (indexes == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (indexes));\n\n\t\t\tif (request == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (request));\n\n\t\t\tif (request.ChangedSince.HasValue && !supportsModSeq)\n\t\t\t\tthrow new NotSupportedException (\"The ImapFolder does not support mod-sequences.\");\n\n\t\t\tif (request.PartialRange.HasValue)\n\t\t\t\tthrow new NotSupportedException (\"The PARTIAL extension only supports UID-based FETCH requests.\");\n\n\t\t\tCheckState (true, false);\n\t\t\tCheckAllowIndexes ();\n\n\t\t\treturn indexes.Count > 0 && !IsEmptyFetchRequest (request);\n\t\t}\n\n\t\tImapCommand QueueFetchCommand (IList<int> indexes, IFetchRequest request, CancellationToken cancellationToken, out bool previewText)\n\t\t{\n\t\t\tvar query = FormatSummaryItems (Engine, request, out previewText);\n\t\t\tvar set = ImapUtils.FormatIndexSet (Engine, indexes);\n\t\t\tvar changedSince = string.Empty;\n\n\t\t\tif (request.ChangedSince.HasValue)\n\t\t\t\tchangedSince = string.Format (CultureInfo.InvariantCulture, \" (CHANGEDSINCE {0})\", request.ChangedSince.Value);\n\n\t\t\tvar command = string.Format (\"FETCH {0} {1}{2}\\r\\n\", set, query, changedSince);\n\t\t\tvar ic = new ImapCommand (Engine, cancellationToken, this, command);","sourceCodeStart":1340,"sourceCodeEnd":1376,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/Net/Imap/ImapFolderFetch.cs#L1340-L1376","documentation":"CheckCanFetch(IList<int>, IFetchRequest) throws this NotSupportedException when request.PartialRange is set on an index-based (sequence number) Fetch call. The PARTIAL fetch modifier is only defined for UID FETCH commands, so MailKit forbids combining PartialRange with index-based Fetch/FetchAsync.","triggerScenarios":"Calling Fetch(IList<int> indexes, IFetchRequest request) or FetchAsync with request.PartialRange.HasValue — PARTIAL requires the UID-based Fetch(uids, request) overload.","commonSituations":"Reusing a single FetchRequest object (with PartialRange set) across both UID and index fetch paths; switching code from UID fetch to index fetch without clearing the request.","solutions":["Use the UID-based overload: convert indexes to UIDs (e.g. via folder.Fetch UIDs / GetMessageUids) and call Fetch(uids, request)","Create a separate IFetchRequest without PartialRange for index-based fetches","Set request.PartialRange = null before index-based Fetch calls"],"exampleFix":"// before\nrequest.PartialRange = partial;\nvar summaries = folder.Fetch(indexes, request); // throws\n// after\nrequest.PartialRange = null;\nvar summaries = folder.Fetch(indexes, request); // or use folder.Fetch(uids, requestWithPartial)","handlingStrategy":"validation","validationCode":"if (request.PartialRange.HasValue)\n    throw new InvalidOperationException(\"Use the UID-based Fetch overload for PartialRange.\");\nvar summaries = folder.Fetch(indexes, request);","typeGuard":null,"tryCatchPattern":"try {\n    summaries = folder.Fetch(indexes, request);\n} catch (NotSupportedException ex) when (ex.Message.Contains(\"UID-based\")) {\n    request.PartialRange = null;\n    summaries = folder.Fetch(indexes, request);\n}","preventionTips":["Never share one FetchRequest instance between UID-partial and index fetch paths","Clear PartialRange before any index/range-based Fetch","Convert indexes to UIDs when partial retrieval is required"],"tags":["imap","mailkit","not-supported","partial","fetch","uid"],"backgroundTag":"mutually-exclusive-options","analyzedSha":"9d3859a7855e3e17582c07fd01972b8e262bf176","analyzedAt":"2026-09-15T15:46:11.592Z","contentChangedAt":"2026-09-15T15:46:11.592Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}