microsoft/FASTER · error · FasterException

Unsupported full checkpoint type

Error message

Unsupported full checkpoint type

What it means

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.

Solutions

  1. Pass only CheckpointType.FoldOver or CheckpointType.Snapshot
  2. Validate the enum value parsed from configuration before calling the checkpoint API
  3. Ensure the library version supports the checkpoint type you specify

Example fix

// before
await fasterKV.TakeFullCheckpointAsync((CheckpointType)settings.CheckpointTypeNum);
// after
var type = (CheckpointType)settings.CheckpointTypeNum;
if (type != CheckpointType.FoldOver && type != CheckpointType.Snapshot)
    throw new InvalidOperationException($"Unsupported checkpoint type: {type}");
await fasterKV.TakeFullCheckpointAsync(type);
Defensive patterns

Strategy: validation

Validate before calling

if (checkpointType is not (CheckpointType.FoldOver or CheckpointType.Snapshot))
    throw new ArgumentException($"Unsupported checkpoint type: {checkpointType}");

Try / catch

try { await fasterKV.TakeFullCheckpointAsync(checkpointType); }
catch (FasterException ex) when (ex.Message == "Unsupported full checkpoint type")
{
    await fasterKV.TakeFullCheckpointAsync(CheckpointType.FoldOver); // safe default
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at cs/src/core/Index/FASTER/FASTER.cs:284

        /// <param name="targetVersion">
        /// intended version number of the next version. Checkpoint will not execute if supplied version is not larger
        /// than current version. Actual new version may have version number greater than supplied number. If the supplied
        /// number is -1, checkpoint will unconditionally create a new version. 
        /// </param>
        /// <returns>
        /// Whether we successfully initiated the checkpoint (initiation may
        /// fail if we are already taking a checkpoint or performing some other
        /// operation such as growing the index). Use CompleteCheckpointAsync to wait completion.
        /// </returns>
        public bool TryInitiateFullCheckpoint(out Guid token, CheckpointType checkpointType, long targetVersion = -1)
        {
            ISynchronizationTask backend;
            if (checkpointType == CheckpointType.FoldOver)
                backend = new FoldOverCheckpointTask();
            else if (checkpointType == CheckpointType.Snapshot)
                backend = new SnapshotCheckpointTask();
            else
                throw new FasterException("Unsupported full checkpoint type");

            var result = StartStateMachine(new FullCheckpointStateMachine(backend, targetVersion));
            if (result)
                token = _hybridLogCheckpointToken;
            else
                token = default;
            return result;
        }

        /// <summary>
        /// Take full (index + log) checkpoint
        /// </summary>
        /// <param name="checkpointType">Checkpoint type</param>
        /// <param name="cancellationToken">Cancellation token</param>
        /// <param name="targetVersion">
        /// intended version number of the next version. Checkpoint will not execute if supplied version is not larger
        /// than current version. Actual new version may have version number greater than supplied number. If the supplied
        /// number is -1, checkpoint will unconditionally create a new version.

View on GitHub (pinned to 321d872eab)