microsoft/FASTER · error · FasterException

Invalid checksum for checkpoint

Error message

Invalid checksum for checkpoint

What it means

After reading all fields of an object-store checkpoint info file (guid, hashes, offsets, continue tokens, etc.), Recover computes a checksum over the parsed values and compares it with the checksum stored in the file. A mismatch means the checkpoint file is corrupt, truncated, or was modified after being written, so recovery is aborted with FasterException("Invalid checksum for checkpoint").

Solutions

  1. Restore a complete checkpoint set (info file + log/object files) from backup; do not hand-edit checkpoint files.
  2. Verify the checkpoint commit completed (CommitInfo/commit record valid) before attempting recovery.
  3. Re-copy the checkpoint with all files if transferring between environments.
  4. If the latest checkpoint is unusable, recover from an earlier valid checkpoint token.

Example fix

// before: recovering with a hand-copied, incomplete info file
faster.Recover(latestToken); // Invalid checksum for checkpoint

// after: use the checkpoint manager to enumerate and validate the full checkpoint
foreach (var cp in manager.GetCheckpointTokens())
    try { faster.Recover(cp); break; } catch (FasterException) { /* try earlier checkpoint */ }
Defensive patterns

Strategy: try-catch

Try / catch

try { faster.Recover(token); } catch (FasterException ex) when (ex.Message == "Invalid checksum for checkpoint") { faster.Recover(previousGoodToken); }

Prevention

When it happens

Trigger: Calling Recover (object checkpoint) when the parsed checksum != Checksum(continueTokens.Count) at the end of Initialize over the checkpoint info stream.

Common situations: Truncated checkpoint info file from a crash during checkpoint commit; manual edits to checkpoint files; copying checkpoint files partially (e.g. missing tail lines) between machines or storage accounts.

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/4a7af876bb56fdea. Report an issue: GitHub.

Appendix: source

Thrown at cs/src/core/Index/Common/Contexts.cs:542

                }
                if (sessionID > maxSessionID) maxSessionID = sessionID;
            }

            // Read object log segment offsets
            value = reader.ReadLine();
            var numSegments = int.Parse(value);
            if (numSegments > 0)
            {
                objectLogSegmentOffsets = new long[numSegments];
                for (int i = 0; i < numSegments; i++)
                {
                    value = reader.ReadLine();
                    objectLogSegmentOffsets[i] = long.Parse(value);
                }
            }

            if (checksum != Checksum(continueTokens.Count))
                throw new FasterException("Invalid checksum for checkpoint");
        }

        /// <summary>
        ///  Recover info from token
        /// </summary>
        /// <param name="token"></param>
        /// <param name="checkpointManager"></param>
        /// <param name="deltaLog"></param>
        /// <param name = "scanDelta">
        /// whether to scan the delta log to obtain the latest info contained in an incremental snapshot checkpoint.
        /// If false, this will recover the base snapshot info but avoid potentially expensive scans.
        /// </param>
        /// <param name="recoverTo"> specific version to recover to, if using delta log</param>
        internal void Recover(Guid token, ICheckpointManager checkpointManager, DeltaLog deltaLog = null, bool scanDelta = false, long recoverTo = -1)
        {
            var metadata = checkpointManager.GetLogCheckpointMetadata(token, deltaLog, scanDelta, recoverTo);
            if (metadata == null)
                throw new FasterException("Invalid log commit metadata for ID " + token.ToString());

View on GitHub (pinned to 321d872eab)