{"record":{"id":"5eab62aab834e8cb","repo":"jstedfast/MailKit","slug":"offset","errorCode":null,"errorMessage":"offset","messagePattern":"offset","errorType":"validation","errorClass":"ArgumentOutOfRangeException","httpStatus":null,"severity":"error","filePath":"MailKit/MailFolder.cs","lineNumber":6212,"sourceCode":"\t\t/// <exception cref=\"System.IO.IOException\">\n\t\t/// An I/O error occurred.\n\t\t/// </exception>\n\t\t/// <exception cref=\"ProtocolException\">\n\t\t/// The server's response contained unexpected tokens.\n\t\t/// </exception>\n\t\t/// <exception cref=\"CommandException\">\n\t\t/// The command failed.\n\t\t/// </exception>\n\t\tpublic virtual Stream GetStream (UniqueId uid, BodyPart part, int offset, int count, CancellationToken cancellationToken = default, ITransferProgress? progress = null)\n\t\t{\n\t\t\tif (!uid.IsValid)\n\t\t\t\tthrow new ArgumentException (\"The uid is invalid.\", nameof (uid));\n\n\t\t\tif (part == null)\n\t\t\t\tthrow new ArgumentNullException (nameof (part));\n\n\t\t\tif (offset < 0)\n\t\t\t\tthrow new ArgumentOutOfRangeException (nameof (offset));\n\n\t\t\tif (count < 0)\n\t\t\t\tthrow new ArgumentOutOfRangeException (nameof (count));\n\n\t\t\treturn GetStream (uid, part.PartSpecifier, offset, count, cancellationToken, progress);\n\t\t}\n\n\t\t/// <summary>\n\t\t/// Asynchronously get a substream of the specified body part.\n\t\t/// </summary>\n\t\t/// <remarks>\n\t\t/// Asynchronously gets a substream of the body part. If the starting offset is beyond\n\t\t/// the end of the body part, an empty stream is returned. If the number of\n\t\t/// bytes desired extends beyond the end of the body part, a truncated stream\n\t\t/// will be returned.\n\t\t/// </remarks>\n\t\t/// <returns>The stream.</returns>\n\t\t/// <param name=\"uid\">The UID of the message.</param>","sourceCodeStart":6194,"sourceCodeEnd":6230,"githubUrl":"https://github.com/jstedfast/MailKit/blob/9d3859a7855e3e17582c07fd01972b8e262bf176/MailKit/MailFolder.cs#L6194-L6230","documentation":"MailFolder.GetStream(UniqueId uid, BodyPart part, int offset, int count, ...) throws ArgumentOutOfRangeException with the message \"offset\" when a negative byte offset into the body part's stream is supplied. The library requires offsets to be zero or positive because they are forwarded to the IMAP server as a partial-fetch start position; a negative value has no meaning in the protocol.","triggerScenarios":"Calling MailFolder.GetStream(uid, part, offset, count) with offset < 0, typically the result of a bad variable, an unvalidated subtraction (e.g. chunkStart - chunkOverlap with chunkOverlap > chunkStart), or an uninitialized int defaulting below zero.","commonSituations":"Implementing resumable/partial downloads where chunk math goes negative on the first chunk; computing offsets from parsed message size fields that failed; copying offset logic from a sync/async overload that had a different coordinate convention.","solutions":["Verify the offset is >= 0 before calling GetStream and clamp or reject negative values","Fix the arithmetic that produces the offset (e.g. Math.Max(0, chunkStart - overlap))","Ensure the value passed is the byte offset within the part, not a message index or UID"],"exampleFix":"// before\nawait folder.GetStream(uid, part, offset, count);\n// after\nif (offset < 0) throw new ArgumentException(\"Offset must be >= 0\");\nawait folder.GetStream(uid, part, Math.Max(0, offset), count);","handlingStrategy":"validation","validationCode":"if (offset < 0) throw new ArgumentException(\"offset must be >= 0\", nameof(offset));","typeGuard":"static bool IsValidOffset(int offset) => offset >= 0;","tryCatchPattern":"try {\n    var stream = folder.GetStream(uid, part, offset, count);\n} catch (ArgumentOutOfRangeException ex) when (ex.ParamName == \"offset\") {\n    // fix offset and retry\n}","preventionTips":["Always clamp computed offsets with Math.Max(0, value)","Never use negative values as sentinels for offsets","Keep chunk-download offset math in one tested helper"],"tags":["argument-validation","mailkit","imap","range"],"backgroundTag":"argument-out-of-range","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"}