microsoft/FASTER · error · FasterException

Invalid checksum found during commit recovery

Error message

Invalid checksum found during commit recovery

What it means

During FasterLog recovery, FasterLogRecoveryInfo.Initialize computes a checksum over the commit record fields (BeginAddress ^ UntilAddress, plus CommitNum/iteratorCount/cookie fields for newer versions) and compares it with the stored checksum. This variant is thrown when the commit record is entirely zeroed (version 0 with all-zero fields), meaning no valid commit was ever persisted. It signals that recovery found an empty or uninitialized commit record rather than real checkpoint state.

Solutions

  1. If the log is expected to be new, ensure the commit metadata file does not exist or is deleted so recovery takes the fresh-log path.
  2. Verify you are pointing FasterLog at the correct checkpoint directory / device path; a wrong path to an empty commit file is common.
  3. Check for disk corruption or incomplete checkpoint commits; re-run checkpointing from a known-good checkpoint.
  4. If state is unrecoverable, create a new FasterLog and re-ingest data from a backup.

Example fix

// before: recovering over an empty commit file
var log = new FasterLog(new FasterLogSettings { LogDevice = device, CheckpointManager = manager });
// FasterException: Invalid checksum found during commit recovery

// after: validate the commit metadata exists and is non-empty before recovering
if (!File.Exists(commitFilePath) || new FileInfo(commitFilePath).Length == 0)
    throw new InvalidOperationException($"No valid commit metadata at {commitFilePath}; cannot recover");
var log = new FasterLog(new FasterLogSettings { LogDevice = device, CheckpointManager = manager });
Defensive patterns

Strategy: validation

Validate before calling

// before recovering, ensure the commit metadata is present and non-empty
if (!File.Exists(commitMetaPath) || new FileInfo(commitMetaPath).Length == 0)
    throw new InvalidOperationException($"No committed log metadata at {commitMetaPath}");

Try / catch

try { log = new FasterLog(settings); } catch (FasterException ex) when (ex.Message.Contains("Invalid checksum found during commit recovery")) { log = new FasterLog(freshSettings); /* start new log */ }

Prevention

When it happens

Trigger: Calling FasterLog recovery (e.g. creating a FasterLog on a device whose commit record was never written) when version == 0 and BeginAddress, UntilAddress, and iteratorCount are all 0, so the zero-check guard in Initialize fires.

Common situations: Starting a log against a fresh/empty device or commit file; the commit metadata file was truncated or zero-filled by disk corruption or a partial format; pointing FasterLog at the wrong directory containing an empty commit file.

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/62feab4aa35272fc. Report an issue: GitHub.

Appendix: source

Thrown at cs/src/core/FasterLog/FasterLogRecoveryInfo.cs:141

                if (cookieLength >= 0)
                {
                    Cookie = reader.ReadBytes(cookieLength);
                    unsafe
                    {
                        fixed (byte* ptr = Cookie)
                            cookieChecksum = (long)Utility.XorBytes(ptr, cookieLength);
                    }
                }
            }

            long computedChecksum = BeginAddress ^ UntilAddress;
            if (version >= FasterLogRecoveryVersion)
                computedChecksum ^= CommitNum ^ iteratorCount ^ cookieLength ^ cookieChecksum;

            // Handle case where all fields are zero
            if (version == 0 && BeginAddress == 0 && UntilAddress == 0 && iteratorCount == 0)
                throw new FasterException("Invalid checksum found during commit recovery");

            if (checkSum != computedChecksum)
                throw new FasterException("Invalid checksum found during commit recovery");
        }

        /// <summary>
        /// Reset
        /// </summary>
        public void Reset()
        {
            Initialize();
        }

        /// <summary>
        /// Write info to byte array
        /// </summary>
        public readonly byte[] ToByteArray()
        {

View on GitHub (pinned to 321d872eab)