microsoft/FASTER · error · FasterException

Invalid checkpoint version

Error message

Invalid checkpoint version {cversion} encountered, current version is {CheckpointVersion}, cannot recover with this checkpoint

What it means

While recovering object-store checkpoint info from a token-completed checkpoint file, the reader parses a checkpoint version and compares it to the code's CheckpointVersion. Only a direct match, or the special v4->v5 translation path, is accepted; anything else throws FasterException with the offending and expected versions. The checkpoint was written by an incompatible version of the library.

Solutions

  1. Use the same library version that wrote the checkpoint to perform recovery, then re-checkpoint and migrate.
  2. If migrating v4 checkpoints, use a version supporting the v4->v5 translation (CheckpointVersion 5).
  3. Checkpoints cannot be downgraded: export data via TakeFullCheckpoint + application-level export from the newer version instead.
  4. Inspect the checkpoint file's version line to confirm what wrote it before attempting recovery.

Example fix

// before: recovering a v4 checkpoint with a v6 binary
faster.Recover(token); // FasterException: Invalid checkpoint version 4 ... current is 6

// after: recover with a v5-capable binary (supports 4->5 translation) or matching version
faster.Recover(token); // succeeds when CheckpointVersion == 5 with translateV4toV5
Defensive patterns

Strategy: validation

Validate before calling

// read the checkpoint version line and compare before recovering
var firstLine = File.ReadLines(infoFilePath).First();
int cversion = int.Parse(firstLine);
if (cversion != CheckpointVersion && !(cversion == 4 && CheckpointVersion == 5))
    throw new InvalidOperationException($"Checkpoint version {cversion} incompatible with runtime version {CheckpointVersion}");

Try / catch

try { faster.Recover(token); } catch (FasterException ex) when (ex.Message.StartsWith("Invalid checkpoint version")) { // recover with a binary of the writing version or migrate checkpoints separately }

Prevention

When it happens

Trigger: Calling Recover (object checkpoint) on a checkpoint whose first line version cversion != CheckpointVersion and where translateV4toV5 (cversion==4, current==5) does not apply.

Common situations: Upgrading or downgrading the FasterLog/FASTER library and then recovering an old checkpoint; restoring checkpoints produced by a fork or different build; opening checkpoints from a newer library with an older binary.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

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

            objectLogSegmentOffsets = null;
        }

        /// <summary>
        /// Initialize from stream
        /// </summary>
        /// <param name="reader"></param>
        public void Initialize(StreamReader reader)
        {
            continueTokens = new();

            string value = reader.ReadLine();
            var cversion = int.Parse(value);

            bool translateV4toV5 = (cversion == 4 && CheckpointVersion == 5);

            if (cversion != CheckpointVersion && !translateV4toV5)
                throw new FasterException($"Invalid checkpoint version {cversion} encountered, current version is {CheckpointVersion}, cannot recover with this checkpoint");

            value = reader.ReadLine();
            var checksum = long.Parse(value);

            value = reader.ReadLine();
            guid = Guid.Parse(value);

            value = reader.ReadLine();
            useSnapshotFile = int.Parse(value);

            value = reader.ReadLine();
            version = long.Parse(value);

            value = reader.ReadLine();
            nextVersion = long.Parse(value);

            value = reader.ReadLine();
            flushedLogicalAddress = long.Parse(value);

View on GitHub (pinned to 321d872eab)