{"record":{"id":"5b8c7c499999d14e","repo":"microsoft/FASTER","slug":"invalid-checkpoint-version-cversion-encountered-current","errorCode":null,"errorMessage":"Invalid checkpoint version {cversion} encountered, current version is {CheckpointVersion}, cannot recover with this checkpoint","messagePattern":"Invalid checkpoint version (.+?) encountered, current version is (.+?), cannot recover with this checkpoint","errorType":"exception","errorClass":"FasterException","httpStatus":null,"severity":"error","filePath":"cs/src/core/Index/Common/Contexts.cs","lineNumber":449,"sourceCode":"\n            objectLogSegmentOffsets = null;\n        }\n\n        /// <summary>\n        /// Initialize from stream\n        /// </summary>\n        /// <param name=\"reader\"></param>\n        public void Initialize(StreamReader reader)\n        {\n            continueTokens = new();\n\n            string value = reader.ReadLine();\n            var cversion = int.Parse(value);\n\n            bool translateV4toV5 = (cversion == 4 && CheckpointVersion == 5);\n\n            if (cversion != CheckpointVersion && !translateV4toV5)\n                throw new FasterException($\"Invalid checkpoint version {cversion} encountered, current version is {CheckpointVersion}, cannot recover with this checkpoint\");\n\n            value = reader.ReadLine();\n            var checksum = long.Parse(value);\n\n            value = reader.ReadLine();\n            guid = Guid.Parse(value);\n\n            value = reader.ReadLine();\n            useSnapshotFile = int.Parse(value);\n\n            value = reader.ReadLine();\n            version = long.Parse(value);\n\n            value = reader.ReadLine();\n            nextVersion = long.Parse(value);\n\n            value = reader.ReadLine();\n            flushedLogicalAddress = long.Parse(value);","sourceCodeStart":431,"sourceCodeEnd":467,"githubUrl":"https://github.com/microsoft/FASTER/blob/321d872eabda6a0345c8bd76419f89723ed864ae/cs/src/core/Index/Common/Contexts.cs#L431-L467","documentation":"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.","triggerScenarios":"Calling Recover (object checkpoint) on a checkpoint whose first line version cversion != CheckpointVersion and where translateV4toV5 (cversion==4, current==5) does not apply.","commonSituations":"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.","solutions":["Use the same library version that wrote the checkpoint to perform recovery, then re-checkpoint and migrate.","If migrating v4 checkpoints, use a version supporting the v4->v5 translation (CheckpointVersion 5).","Checkpoints cannot be downgraded: export data via TakeFullCheckpoint + application-level export from the newer version instead.","Inspect the checkpoint file's version line to confirm what wrote it before attempting recovery."],"exampleFix":"// before: recovering a v4 checkpoint with a v6 binary\nfaster.Recover(token); // FasterException: Invalid checkpoint version 4 ... current is 6\n\n// after: recover with a v5-capable binary (supports 4->5 translation) or matching version\nfaster.Recover(token); // succeeds when CheckpointVersion == 5 with translateV4toV5","handlingStrategy":"validation","validationCode":"// read the checkpoint version line and compare before recovering\nvar firstLine = File.ReadLines(infoFilePath).First();\nint cversion = int.Parse(firstLine);\nif (cversion != CheckpointVersion && !(cversion == 4 && CheckpointVersion == 5))\n    throw new InvalidOperationException($\"Checkpoint version {cversion} incompatible with runtime version {CheckpointVersion}\");","typeGuard":null,"tryCatchPattern":"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 }","preventionTips":["Pin the library version across all services sharing checkpoints.","Re-checkpoint after upgrading so new checkpoints use the current version.","Test version-skew recovery in staging before upgrades."],"tags":["checkpoint","version-mismatch","recovery","compatibility"],"backgroundTag":"incompatible-source-type","analyzedSha":"321d872eabda6a0345c8bd76419f89723ed864ae","analyzedAt":"2026-09-15T22:18:00.693Z","contentChangedAt":"2026-09-15T22:18:00.693Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}