microsoft/FASTER · error · FasterException

Invalid checksum found during scan, skipping

Error message

Invalid checksum found during scan, skipping

What it means

The iterator verified a record's checksum below the head address and it did not match (FasterLogIterator.cs:853). The record's data was corrupted after being committed, so the iterator skips past it and throws to alert the caller that durable data was compromised.

Solutions

1. Restore the affected page(s) from a known-good checkpoint or backup.
2. Check and repair storage health (fsck/SMART); avoid storage layers without end-to-end integrity.
3. If tolerable, catch this exception in the iteration loop and treat it as a poison-record skip, continuing the scan.
4. Re-verify the whole log after recovery and re-run any side effects derived from the corrupt records.

Example fix

// before
await foreach (var e in iter.GetAsyncEnumerable()) { ... } // throws mid-scan

// after
while (iter.GetNext(out var entry, out var addr))
{
    try { Process(entry, addr); }
    catch (FasterException ex) when (ex.Message.Contains("Invalid checksum")) { /* skip poisoned record */ }
}

while (iter.GetNext(out var entry, out var addr))
{
    try { Process(entry, addr); }
    catch (FasterException ex) when (ex.Message.Contains("Invalid checksum")) { logWarn(addr); continue; }
}

When it happens

Trigger: Scanning older (already checkpointed/on-disk) regions where a record's bytes were mutated — storage bit rot, torn page writes, or copying log files without a checkpoint; hardware faults.

Common situations: Restored backups whose files were manually modified; NFS/network storage with silent corruption; partial checkpoint restore; disk returning stale data after a crash.

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

• Invalid length of record found
• Checksum failed for read
• Uninitialized page found during scan at page
• Invalid checksum found during commit recovery
• Cannot use named iterators with read-only FasterLog

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

Appendix: source

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

                }

                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;
                }

                // Verify checksum if needed
                if (currentAddress < _headAddress)
                {
                    if (!fasterLog.VerifyChecksum((byte*)physicalAddress, entryLength))
                    {
                        currentAddress += headerSize;
                        if (Utility.MonotonicUpdate(ref nextAddress, currentAddress, out _))
                            throw new FasterException("Invalid checksum found during scan, skipping");
                        continue;
                    }
                }

                if ((currentAddress & allocator.PageSizeMask) + recordSize == allocator.PageSize)
                    currentAddress = (1 + (currentAddress >> allocator.LogPageSizeBits)) << allocator.LogPageSizeBits;
                else
                    currentAddress += recordSize;

                if (Utility.MonotonicUpdate(ref nextAddress, currentAddress, out long oldCurrentAddress))
                {
                    outNextAddress = currentAddress;
                    currentAddress = oldCurrentAddress;
                    return true;
                }
            }
        }

View on GitHub (pinned to 321d872eab)