{"record":{"id":"d24ec554515611fd","repo":"microsoft/FASTER","slug":"unsupported-full-checkpoint-type","errorCode":null,"errorMessage":"Unsupported full checkpoint type","messagePattern":"Unsupported full checkpoint type","errorType":"exception","errorClass":"FasterException","httpStatus":null,"severity":"error","filePath":"cs/src/core/Index/FASTER/FASTER.cs","lineNumber":284,"sourceCode":"        /// <param name=\"targetVersion\">\n        /// intended version number of the next version. Checkpoint will not execute if supplied version is not larger\n        /// than current version. Actual new version may have version number greater than supplied number. If the supplied\n        /// number is -1, checkpoint will unconditionally create a new version. \n        /// </param>\n        /// <returns>\n        /// Whether we successfully initiated the checkpoint (initiation may\n        /// fail if we are already taking a checkpoint or performing some other\n        /// operation such as growing the index). Use CompleteCheckpointAsync to wait completion.\n        /// </returns>\n        public bool TryInitiateFullCheckpoint(out Guid token, CheckpointType checkpointType, long targetVersion = -1)\n        {\n            ISynchronizationTask backend;\n            if (checkpointType == CheckpointType.FoldOver)\n                backend = new FoldOverCheckpointTask();\n            else if (checkpointType == CheckpointType.Snapshot)\n                backend = new SnapshotCheckpointTask();\n            else\n                throw new FasterException(\"Unsupported full checkpoint type\");\n\n            var result = StartStateMachine(new FullCheckpointStateMachine(backend, targetVersion));\n            if (result)\n                token = _hybridLogCheckpointToken;\n            else\n                token = default;\n            return result;\n        }\n\n        /// <summary>\n        /// Take full (index + log) checkpoint\n        /// </summary>\n        /// <param name=\"checkpointType\">Checkpoint type</param>\n        /// <param name=\"cancellationToken\">Cancellation token</param>\n        /// <param name=\"targetVersion\">\n        /// intended version number of the next version. Checkpoint will not execute if supplied version is not larger\n        /// than current version. Actual new version may have version number greater than supplied number. If the supplied\n        /// number is -1, checkpoint will unconditionally create a new version. ","sourceCodeStart":266,"sourceCodeEnd":302,"githubUrl":"https://github.com/microsoft/FASTER/blob/321d872eabda6a0345c8bd76419f89723ed864ae/cs/src/core/Index/FASTER/FASTER.cs#L266-L302","documentation":"TryInitiateFullCheckpoint only supports CheckpointType.FoldOver and CheckpointType.Snapshot; any other value hits the else branch and throws. It's a guard against passing an unknown/invalid enum value when initiating a full checkpoint.","triggerScenarios":"Calling TakeFullCheckpointAsync/TakeFullCheckpoint (or TryInitiateFullCheckpoint via its callers) with checkpointType set to an undefined CheckpointType value, e.g. (CheckpointType)99 from a config field or deserialized data.","commonSituations":"Reading the checkpoint type from configuration or a database column holding an out-of-range numeric value; enum added in a newer library version but run on older binaries; typo-driven cast errors.","solutions":["Pass only CheckpointType.FoldOver or CheckpointType.Snapshot","Validate the enum value parsed from configuration before calling the checkpoint API","Ensure the library version supports the checkpoint type you specify"],"exampleFix":"// before\nawait fasterKV.TakeFullCheckpointAsync((CheckpointType)settings.CheckpointTypeNum);\n// after\nvar type = (CheckpointType)settings.CheckpointTypeNum;\nif (type != CheckpointType.FoldOver && type != CheckpointType.Snapshot)\n    throw new InvalidOperationException($\"Unsupported checkpoint type: {type}\");\nawait fasterKV.TakeFullCheckpointAsync(type);","handlingStrategy":"validation","validationCode":"if (checkpointType is not (CheckpointType.FoldOver or CheckpointType.Snapshot))\n    throw new ArgumentException($\"Unsupported checkpoint type: {checkpointType}\");","typeGuard":null,"tryCatchPattern":"try { await fasterKV.TakeFullCheckpointAsync(checkpointType); }\ncatch (FasterException ex) when (ex.Message == \"Unsupported full checkpoint type\")\n{\n    await fasterKV.TakeFullCheckpointAsync(CheckpointType.FoldOver); // safe default\n}","preventionTips":["Never cast raw integers to CheckpointType without range validation","Whitelist enum values when loading checkpoint type from config/db","Keep enum constants in sync with the library version"],"tags":["checkpoint","enum","invalid-argument"],"backgroundTag":"invalid-enum-value","analyzedSha":"321d872eabda6a0345c8bd76419f89723ed864ae","analyzedAt":"2026-09-15T22:18:00.693Z","contentChangedAt":"2026-09-15T22:18:00.693Z","schemaVersion":2},"datasetVersion":"2026-09-23T02:17:17.105Z"}