microsoft/FASTER · error · FasterException

Uninitialized page found during scan at page

Error message

Uninitialized page found during scan at page {page}

What it means

During GetNextInternal scanning, the iterator reached a page whose start is zeroed out — no valid record header — meaning the page was never initialized/committed (FasterLogIterator.cs:825). This surfaces corrupt or unwritten storage during recovery/tail scan rather than silently skipping data.

Solutions

  1. Restrict the scan to the log's committed range (use SafeTailAddress/CommittedUntilAddress as the scan end).
  2. Verify the log directory contents match the checkpoint (all device files present, not truncated).
  3. Recover from an earlier checkpoint if on-disk pages are damaged; investigate storage/device health.
  4. If using replication, ensure the replica has caught up before iterating past the local committed tail.

Example fix

// before
using var iter = log.Scan(beginAddress, long.MaxValue);

// after
using var iter = log.Scan(beginAddress, log.CommittedUntilAddress);
Defensive patterns

Strategy: validation

Validate before calling

if (endAddress > log.CommittedUntilAddress) endAddress = log.CommittedUntilAddress; // never scan past committed tail

Try / catch

try { while (iter.GetNext(out var e, out var a)) Process(e, a); } catch (FasterException ex) when (ex.Message.StartsWith("Uninitialized page found")) { /* stop scan; verify checkpoint/storage */ }

Prevention

When it happens

Trigger: Scanning into a page region beyond what was durably committed (e.g., iterating past the confirmed tail after a crash), damaged/truncated device backing store, or misconfigured log directory where the iterator head/tail metadata disagrees with on-disk pages.

Common situations: Crash mid-write leaving a partially flushed page; restoring a checkpoint without all log files; disk/data loss in the log directory; reading a replicated log while replication is incomplete.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

AI-assisted analysis of microsoft/FASTER@321d872eab (2026-09-15). Data as JSON: /api/errors/04d331e034713a70. Report an issue: GitHub.

Appendix: source

Thrown at cs/src/core/FasterLog/FasterLogIterator.cs:825

                {
                    physicalAddress = allocator.GetPhysicalAddress(currentAddress);
                }

                // Get and check entry length
                entryLength = fasterLog.GetLength((byte*)physicalAddress);

                // We may encounter zeroed out bits at the end of page in a normal log, therefore, we need to check whether that is the case
                if (entryLength == 0)
                {
                    // Zero-ed out bytes could be padding at the end of page, first jump to the start of next page. 
                    var  nextStart = (1 + (currentAddress >> allocator.LogPageSizeBits)) << allocator.LogPageSizeBits;
                    if (Utility.MonotonicUpdate(ref nextAddress, nextStart, out _))
                    {
                        var pageOffset = currentAddress & ((1 << allocator.LogPageSizeBits) - 1);

                        // If zeroed out field is at page start, we encountered an uninitialized page and should signal up
                        if (pageOffset == 0)
                            throw new FasterException("Uninitialized page found during scan at page " + (currentAddress >> allocator.LogPageSizeBits));
                    }
                    continue;
                }

                // commit records have negative length fields
                if (entryLength < 0)
                {
                    commitRecord = true;
                    entryLength = -entryLength;
                }

                int recordSize = headerSize + Align(entryLength);
                if (_currentOffset + recordSize > allocator.PageSize)
                {
                    currentAddress += headerSize;
                    if (Utility.MonotonicUpdate(ref nextAddress, currentAddress, out _))
                        throw new FasterException("Invalid length of record found: " + entryLength + " at address " + currentAddress);
                    continue;

View on GitHub (pinned to 321d872eab)