microsoft · badrishc · Jun 11, 2026 · May 23, 2026 · May 23, 2026 · May 24, 2026
diff --git a/libs/host/Configuration/Options.cs b/libs/host/Configuration/Options.cs
@@ -581,6 +581,10 @@ internal sealed class Options : ICloneable
         [Option("value-overflow-threshold", Required = false, HelpText = "Max size of a value stored inline in the main-log page (larger values overflow to the heap). Accepts a memory size (e.g. 4k, 1m). Minimum 64 bytes; must be less than PageSize.")]
         public string ValueOverflowThreshold { get; set; }
 
+        [MemorySizeValidation(isRequired: false)]
+        [Option("initial-io-record-size", Required = false, HelpText = "Initial IO read size for records on disk. Accepts a memory size (e.g. 4k, 8k). Default is 128 bytes.")]
+        public string InitialIORecordSize { get; set; }
+
         [OptionValidation]
         [Option("fail-on-recovery-error", Required = false, HelpText = "Server bootup should fail if errors happen during bootup of AOF and checkpointing")]
         public bool? FailOnRecoveryError { get; set; }
@@ -944,6 +948,7 @@ endpoint is IPEndPoint listenEp && clusterAnnounceEndpoint[0] is IPEndPoint anno
                 IndexResizeFrequencySecs = IndexResizeFrequencySecs,
                 IndexResizeThreshold = IndexResizeThreshold,
                 ValueOverflowThreshold = ValueOverflowThreshold,
+                InitialIORecordSize = InitialIORecordSize,
                 LoadModuleCS = LoadModuleCS,
                 FailOnRecoveryError = FailOnRecoveryError.GetValueOrDefault(),
                 LuaOptions = EnableLua.GetValueOrDefault() ? new LuaOptions(LuaMemoryManagementMode, LuaScriptMemoryLimit, LuaScriptTimeoutMs == 0 ? Timeout.InfiniteTimeSpan : TimeSpan.FromMilliseconds(LuaScriptTimeoutMs), LuaLoggingMode, LuaAllowedFunctions, logger) : null,

diff --git a/libs/host/defaults.conf b/libs/host/defaults.conf
@@ -416,6 +416,9 @@
 	/* Max size of a value stored inline in the main-log page (larger values overflow to the heap). Accepts a memory size (e.g. "4k", "1m"). Minimum 64 bytes; must be less than PageSize. */
 	"ValueOverflowThreshold": "16k",
 
+	/* Initial IO read size for records on disk. Accepts a memory size (e.g. "4k", "8k"). null means use the default (128 bytes). */
+	"InitialIORecordSize": null,
+
 	/* List of module paths to be loaded at startup */
 	"LoadModuleCS": null,
 

diff --git a/libs/server/Servers/GarnetServerOptions.cs b/libs/server/Servers/GarnetServerOptions.cs
@@ -127,6 +127,12 @@ public class GarnetServerOptions : ServerOptions
         /// </summary>
         public string ValueOverflowThreshold = "16k";
 
+        /// <summary>
+        /// Initial IO read size for records on disk. Accepts bytes or k/m/g suffixes (e.g. "4k", "8k").
+        /// null means use the default (<see cref="IStreamBuffer.DefaultInitialIORecordSize"/> bytes).
+        /// </summary>
+        public string InitialIORecordSize = null;
+
         /// <summary>
         /// Wait for AOF to commit before returning results to client.
         /// Warning: will greatly increase operation latency.
@@ -629,6 +635,7 @@ public KVSettings GetSettings(ILoggerFactory loggerFactory, LightEpoch epoch, St
                 Epoch = epoch,
                 StateMachineDriver = stateMachineDriver,
                 MaxInlineValueSize = ValueOverflowThresholdBytes(),
+                InitialIORecordSize = GetInitialIORecordSizeBytes(),
                 loggerFactory = loggerFactory,
                 logger = loggerFactory?.CreateLogger("TsavoriteKV [main]")
             };
@@ -872,6 +879,29 @@ public int ValueOverflowThresholdBytes()
             return (int)sizeInBytes;
         }
 
+        /// <summary>
+        /// Parse <see cref="InitialIORecordSize"/> as a byte count.
+        /// Returns <see cref="KVSettings.UseDefaultInitialIORecordSize"/> if the value is null or empty (use default).
+        /// </summary>
+        /// <returns>The byte value used for <c>KVSettings.InitialIORecordSize</c>, or <see cref="KVSettings.UseDefaultInitialIORecordSize"/> if unset.</returns>
+        /// <exception cref="Exception">Thrown when the value cannot be parsed.</exception>
+        public int GetInitialIORecordSizeBytes()
+        {
+            if (string.IsNullOrEmpty(InitialIORecordSize))
+                return KVSettings.UseDefaultInitialIORecordSize;
+
+            if (!TryParseSize(InitialIORecordSize, out var sizeInBytes))
+                throw new Exception($"Unable to parse {nameof(InitialIORecordSize)} value '{InitialIORecordSize}'. Expected a memory size string (e.g. '4k', '8k').");
+
+            if (sizeInBytes <= 0)
+                throw new Exception($"{nameof(InitialIORecordSize)} value '{InitialIORecordSize}' ({sizeInBytes} bytes) must be positive.");
+
+            if (sizeInBytes > 1L << PageSizeBits())
+                throw new Exception($"{nameof(InitialIORecordSize)} value '{InitialIORecordSize}' ({sizeInBytes} bytes) exceeds the page size ({1L << PageSizeBits()} bytes).");
+
+            return (int)sizeInBytes;
+        }
+
         /// <summary>
         /// Get AOF settings
         /// </summary>

diff --git a/libs/storage/Tsavorite/cs/src/core/Allocator/AllocatorBase.cs b/libs/storage/Tsavorite/cs/src/core/Allocator/AllocatorBase.cs
@@ -1679,16 +1679,16 @@ internal void AsyncReadRecordToMemory(long fromLogicalAddress, int numBytes, Dev
         [MethodImpl(MethodImplOptions.NoInlining)]
         internal void AsyncReadBlittableRecordToMemory(long fromLogicalAddress, int numBytes, DeviceIOCompletionCallback callback, ref SimpleReadContext context)
         {
-            context.record = GetAndPopulateReadBuffer(fromLogicalAddress, numBytes, out var alignedFileOffset, out var alignedReadLength);
-            device.ReadAsync(alignedFileOffset, (IntPtr)context.record.aligned_pointer, alignedReadLength, callback, context);
+            context.record = GetAndPopulateReadBuffer(fromLogicalAddress, numBytes, out var alignedReadStart, out var alignedReadLength);
+            device.ReadAsync(alignedReadStart, (IntPtr)context.record.aligned_pointer, alignedReadLength, callback, context);
         }
 
-        private SectorAlignedMemory GetAndPopulateReadBuffer(long fromLogicalAddress, int numBytes, out ulong alignedFileOffset, out uint alignedReadLength)
+        private SectorAlignedMemory GetAndPopulateReadBuffer(long fromLogicalAddress, int numBytes, out ulong alignedReadStart, out uint alignedReadLength)
         {
-            var fileOffset = (ulong)(AlignedPageSizeBytes * GetPage(fromLogicalAddress) + GetOffsetOnPage(fromLogicalAddress));
-            alignedFileOffset = (ulong)RoundDown((long)fileOffset, sectorSize);
-            alignedReadLength = (uint)((long)fileOffset + numBytes - (long)alignedFileOffset);
-            alignedReadLength = (uint)RoundUp(alignedReadLength, sectorSize);
+            var readStart = (ulong)(AlignedPageSizeBytes * GetPage(fromLogicalAddress) + GetOffsetOnPage(fromLogicalAddress));
+            alignedReadStart = (ulong)RoundDown((long)readStart, sectorSize);
+            var alignedReadEnd = (ulong)RoundUp((long)readStart + numBytes, sectorSize);
+            alignedReadLength = (uint)(alignedReadEnd - alignedReadStart);
 
             // Records never span page boundaries (HandlePageOverflow guarantees this), but the
             // sector-aligned read window above can over-extend past the page-end on records near
@@ -1701,16 +1701,16 @@ private SectorAlignedMemory GetAndPopulateReadBuffer(long fromLogicalAddress, in
             // sector-aligned (PageSizeBits >= SectorSize), so the clamped length stays
             // sector-aligned.
             var pageEndInFile = (ulong)(AlignedPageSizeBytes * (GetPage(fromLogicalAddress) + 1));
-            if (alignedFileOffset + alignedReadLength > pageEndInFile)
-                alignedReadLength = (uint)(pageEndInFile - alignedFileOffset);
+            if (alignedReadStart + alignedReadLength > pageEndInFile)
+                alignedReadLength = (uint)(pageEndInFile - alignedReadStart);
 
             // Rent the read-destination buffer with clearOnReturn=false: the device read
             // will fully overwrite [aligned_pointer .. aligned_pointer + alignedReadLength)
             // and downstream consumers bound their access by valid_offset / available_bytes,
             // so the historical Array.Clear on Return is pure waste here (~4-8 KB of memory
             // bandwidth per pending read).
             var record = bufferPool.Get((int)alignedReadLength, clearOnReturn: false);
-            record.valid_offset = (int)(fileOffset - alignedFileOffset);
+            record.valid_offset = (int)(readStart - alignedReadStart);
             record.available_bytes = (int)(alignedReadLength - record.valid_offset);
             record.required_bytes = numBytes;
             return record;
@@ -2104,7 +2104,7 @@ private protected virtual bool VerifyRecordFromDiskCallback(ref AsyncIOContext c
             // TODO: Optimize for non-ReadAtAddress tombstoned records to not have to retrieve the full record or, if we have it, not deserialize objects.
 
             // Initialize to "key is not present (data too small) or does not match so get previous record" length to read
-            prevLengthToRead = IStreamBuffer.InitialIOSize;
+            prevLengthToRead = IStreamBuffer.DefaultInitialIORecordSize;
 
             // See if we have a complete record.
             var currentLength = ctx.record.available_bytes;

diff --git a/libs/storage/Tsavorite/cs/src/core/Allocator/AllocatorScan.cs b/libs/storage/Tsavorite/cs/src/core/Allocator/AllocatorScan.cs
@@ -175,7 +175,7 @@ internal bool GetFromDiskAndPushToReader<TKey, TScanFunctions>(TKey key, ref lon
                 return false;
 
             completionEvent.Prepare(key, logicalAddress, bufferPool);
-            AsyncGetFromDisk(logicalAddress, IStreamBuffer.InitialIOSize, completionEvent.request);
+            AsyncGetFromDisk(logicalAddress, IStreamBuffer.DefaultInitialIORecordSize, completionEvent.request);
             completionEvent.Wait();
 
             ref var request = ref completionEvent.request;

diff --git a/libs/storage/Tsavorite/cs/src/core/Allocator/LogRecord.cs b/libs/storage/Tsavorite/cs/src/core/Allocator/LogRecord.cs
@@ -481,6 +481,26 @@ public static int GetAllocatedSize(long physicalAddress)
 
         #endregion // ISourceLogRecord
 
+        /// <summary>
+        /// Computes the expected allocated record size from component lengths and optional-field expectations, without requiring
+        /// an actual record in memory. This uses the same layout math as <see cref="RecordSizeInfo.CalculateSizes"/>.
+        /// </summary>
+        /// <param name="keyDataLength">Length of the key data in bytes.</param>
+        /// <param name="valueDataLength">Length of the value data in bytes. For object values, use <see cref="ObjectIdMap.ObjectIdSize"/>.</param>
+        /// <param name="extendedNamespaceLength">Length of any extended namespace data preceding the key (0 if none).</param>
+        /// <param name="expectETag">Whether the record is expected to have an ETag optional field.</param>
+        /// <param name="expectExpiration">Whether the record is expected to have an Expiration optional field.</param>
+        /// <param name="expectObject">Whether the record is expected to have an object (key overflow, value overflow, or value object),
+        ///     which requires an <see cref="ObjectLogPositionSize"/>-byte object-log position field.</param>
+        /// <returns>The expected allocated (record-aligned) size in bytes, including <see cref="RecordInfo"/> header.</returns>
+        public static int GetExpectedIORecordSize(int keyDataLength, int valueDataLength, int extendedNamespaceLength = 0,
+            bool expectETag = false, bool expectExpiration = false, bool expectObject = false)
+        {
+            var optionalSize = (expectETag ? ETagSize : 0) + (expectExpiration ? ExpirationSize : 0) + (expectObject ? ObjectLogPositionSize : 0);
+            var actualSize = Constants.FixedHeaderSize + extendedNamespaceLength + keyDataLength + valueDataLength + optionalSize;
+            return Utility.RoundUp(actualSize, Constants.kRecordAlignment);
+        }
+
         /// <summary>Set the filler length on the RDH for a record. Used only by <see cref="DiskLogRecord.DirectCopyInlinePortionOfRecord"/>
         /// when constructing a LogRecord over a transient output buffer (NOT a live log record), so no concurrent scanner exists.
         /// <see cref="RecordDataHeader.SetFiller"/> performs its own atomic word update.</summary>

diff --git a/libs/storage/Tsavorite/cs/src/core/Allocator/MallocFixedPageSize.cs b/libs/storage/Tsavorite/cs/src/core/Allocator/MallocFixedPageSize.cs
@@ -50,6 +50,7 @@ private enum AllocationMode { None, Single, Bulk };
         private AllocationMode allocationMode;
 #endif
 
+        // This is used only for Flush and Restore, not random reads, so 512 is fine.
         const int SectorSize = 512;
 
         private int initialAllocation = 0;

diff --git a/libs/storage/Tsavorite/cs/src/core/Allocator/ObjectScanIterator.cs b/libs/storage/Tsavorite/cs/src/core/Allocator/ObjectScanIterator.cs
@@ -239,10 +239,19 @@ public bool GetNext()
                         try
                         {
                             // Lock to ensure no value tearing while copying to temp storage.
-                            if (currentAddress >= headAddress && store is not null)
+                            if (store is not null)
                             {
                                 var logRecord = hlogBase._wrapper.CreateLogRecord(currentAddress, physicalAddress);
                                 store.LockForScan(ref stackCtx, logRecord);
+
+                                // LockForScan may spin via epoch.ProtectAndDrain(), which advances this thread's localCurrentEpoch and may synchronously fire a
+                                // previously-queued OnPagesClosed action (from a concurrent ShiftHeadAddress). If HeadAddress now exceeds currentAddress, the page
+                                // our physicalAddress points to has been freed and may have been reused; retry this address through the disk-buffering path.
+                                if (currentAddress < hlogBase.HeadAddress)
+                                {
+                                    nextAddress = currentAddress;
+                                    continue;
+                                }
                             }
 
                             if (recordBuffer == null)

diff --git a/libs/storage/Tsavorite/cs/src/core/Allocator/ObjectSerialization/IStreamBuffer.cs b/libs/storage/Tsavorite/cs/src/core/Allocator/ObjectSerialization/IStreamBuffer.cs
@@ -20,15 +20,16 @@ public interface IStreamBuffer : IDisposable
         /// <summary>The size of the buffer used for writing data to and reading it from the disk. Must be a sector multiple.</summary>
         internal const int BufferSize = 1 << LogSettings.kMinObjectLogSegmentSizeBits;
 
-        /// <summary>Initial IO size to read. Sized to comfortably cover a typical small record (header + small key + small value)
+        /// <summary>Default Initial IO size to read; may be overridden by operation-level, session-level, or store-level specification.
+        /// Sized to comfortably cover a typical small record (header + small key + small value)
         /// in one device-sector IO. The previous default of one OS system page (4 KB on Linux x64) caused most reads of small
         /// records to span 4 KB NAND-page boundaries on NVMe, doubling per-IO device latency (~0.92 ms vs ~0.67 ms for sector-aligned
         /// 4 KB reads). With a 128-byte speculative read, the sector-aligned IO is typically 1 sector (and up to 2 sectors when the
         /// record begins near the end of a sector), and usually captures a full small record with no re-read.
         /// Records larger than what fits in the speculative read trigger a precise re-read via VerifyRecordFromDiskCallback with the
         /// now-known recordLength, same as before — the cost is one extra IO per multi-sector record, which is a fair trade against
         /// avoiding the NAND-crossing penalty on every small-record IO.</summary>
-        internal const int InitialIOSize = 128;
+        public const int DefaultInitialIORecordSize = 128;
 
         /// <summary>
         /// We use these buffers for only read or only write operations, never both at the same time.

diff --git a/libs/storage/Tsavorite/cs/src/core/Allocator/ObjectSerialization/ObjectLogReader.cs b/libs/storage/Tsavorite/cs/src/core/Allocator/ObjectSerialization/ObjectLogReader.cs
@@ -81,7 +81,7 @@ internal void OnBeginReadRecords(ObjectLogFilePositionInfo filePosition, ulong t
         /// <item>If we have an Overflow or Object value, read and store it in the transient <see cref="ObjectIdMap"/> in <paramref name="logRecord"/>.</item>
         /// </list>
         /// </summary>
-        /// <param name="logRecord">The initial record read from disk from Pending IO, so it is of size <see cref="IStreamBuffer.InitialIOSize"/> or less.</param>
+        /// <param name="logRecord">The initial record read from disk from Pending IO, so it is of size <see cref="IStreamBuffer.DefaultInitialIORecordSize"/> or less.</param>
         /// <param name="requestedKey">The requested key, if not ReadAtAddress; we will compare to see if it matches the record.</param>
         /// <param name="segmentSizeBits">Number of bits in segment size</param>
         /// <returns>False if requestedKey is set and we read an Overflow key and it did not match; otherwise true</returns>

diff --git a/libs/storage/Tsavorite/cs/src/core/Allocator/ScanIteratorBase.cs b/libs/storage/Tsavorite/cs/src/core/Allocator/ScanIteratorBase.cs
@@ -320,7 +320,15 @@ private bool WaitForFrameLoad(long currentAddress, long currentFrame)
                 loadedPages[currentFrame] = -1;
                 loadCTSs[currentFrame] = new CancellationTokenSource();
                 _ = Utility.MonotonicUpdate(ref nextAddress, GetLogicalAddressOfStartOfPage(1 + GetPageOfAddress(currentAddress, logPageSizeBits), logPageSizeBits), out _);
-                throw new TsavoriteException("Page read from storage failed, skipping page. Inner exception: " + e.ToString());
+
+                // Callers may be looking for an OCE so throw that if it's what we got.
+                if (e is OperationCanceledException)
+                {
+                    logger?.LogWarning(e, "Wait for frame load was canceled, skipping page. CurrentAddress: {currentAddress}, currentFrame: {currentFrame}", AddressString(currentAddress), currentFrame);
+                    throw;
+                }
+                else
+                    throw new TsavoriteException("Page read from storage failed, skipping page. Inner exception: " + e.ToString());
             }
             finally
             {

diff --git a/libs/storage/Tsavorite/cs/src/core/Allocator/SpanByteScanIterator.cs b/libs/storage/Tsavorite/cs/src/core/Allocator/SpanByteScanIterator.cs
@@ -238,10 +238,19 @@ public bool GetNext()
                         try
                         {
                             // Lock to ensure no value tearing while copying to temp storage.
-                            if (currentAddress >= headAddress && store is not null)
+                            if (store is not null)
                             {
                                 var logRecord = hlogBase._wrapper.CreateLogRecord(currentAddress, physicalAddress);
                                 store.LockForScan(ref stackCtx, logRecord);
+
+                                // LockForScan may spin via epoch.ProtectAndDrain(), which advances this thread's localCurrentEpoch and may synchronously fire a
+                                // previously-queued OnPagesClosed action (from a concurrent ShiftHeadAddress). If HeadAddress now exceeds currentAddress, the page
+                                // our physicalAddress points to has been freed and may have been reused; retry this address through the disk-buffering path.
+                                if (currentAddress < hlogBase.HeadAddress)
+                                {
+                                    nextAddress = currentAddress;
+                                    continue;
+                                }
                             }
 
                             if (recordBuffer == null)