microsoft/FASTER · critical · FasterException

Checksum failed for read

Error message

Checksum failed for read

What it means

When reading a record into a byte[] (Read/ReadAsync with byte allocation), FasterLog verifies the record's stored checksum. VerifyChecksum failing means the on-disk bytes no longer match the checksum written with the record - corruption on the log device or a torn/partial write. Thrown at FasterLog.cs:2638.

Solutions

1. Verify the LogDevice contents were not externally modified; restore from a known-good copy/backup.
2. Scan the log to find the last valid record and truncate/reposition iteration before the corrupt address.
3. Test the storage hardware/disk for errors and check for partial writes from a crash; use a device layer with proper flush/fsync.
4. If using a custom IDevice implementation, verify it persists the full record including headers and checksums.

Example fix

// before
var (result, _, _) = log.Read(corruptAddress); // throws on checksum failure
// after
try
{
    var (result, _, _) = log.Read(address);
}
catch (FasterException) // checksum/corruption
{
    // fall back to last known-good address or rebuild log from backup
}

try { var (result, _, _) = log.Read(address); } catch (FasterException ex) when (ex.Message.Contains("Checksum failed")) { // quarantine address, alert, restore from backup, or scan for last valid record
}

When it happens

Trigger: Calling FasterLog.Read / ReadAsync (byte[] overload) at an address whose record bytes were corrupted on the LogDevice - failed disk write, bit rot, external modification of the device file, or reading a partially flushed record.

Common situations: Hardware/disk failures, copying or truncating the log device file externally, buggy custom device implementations (e.g. in-memory or sharded devices not persisting all bytes), or reading past what was safely committed 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
• Invalid checksum found during scan, skipping
• Invalid checksum found during commit recovery
• Unexpected entry type
• Cannot use scanUncommitted without setting…

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

Appendix: source

Thrown at cs/src/core/FasterLog/FasterLog.cs:2638

                }
                ctx.completedRead.Release();
            }
        }

        private (byte[], int) GetRecordAndFree(SectorAlignedMemory record)
        {
            if (record == null)
                return (null, 0);

            byte[] result;
            int length;
            unsafe
            {
                var ptr = record.GetValidPointer();
                length = GetLength(ptr);
                if (!VerifyChecksum(ptr, length))
                {
                    throw new FasterException("Checksum failed for read");
                }
                result = getMemory != null ? getMemory(length) : new byte[length];
                fixed (byte* bp = result)
                {
                    Buffer.MemoryCopy(ptr + headerSize, bp, length, length);
                }
            }
            record.Return();
            return (result, length);
        }

        private (IMemoryOwner<byte>, int) GetRecordAsMemoryOwnerAndFree(SectorAlignedMemory record, MemoryPool<byte> memoryPool)
        {
            if (record == null)
                return (null, 0);

            IMemoryOwner<byte> result;
            int length;

View on GitHub (pinned to 321d872eab)