microsoft/FASTER · error · FasterException

Unsupported checkpoint type

Error message

Unsupported checkpoint type

What it means

TryInitiateHybridLogCheckpoint accepts FoldOver, Snapshot, and (conditionally) Snapshot with incremental support; any other CheckpointType value throws. Like error 124 but for the hybrid-log checkpoint path, where incremental snapshot tasks may substitute for plain snapshot when eligible.

Solutions

1. Pass only CheckpointType.FoldOver or CheckpointType.Snapshot
2. Validate the enum value before initiating the checkpoint
3. Keep the checkpoint type constants in sync with the library version in use

Example fix

// before
await fasterKV.TakeHybridLogCheckpointAsync((CheckpointType)cfg.HlogType);
// after
Debug.Assert(cfg.HlogType is CheckpointType.FoldOver or CheckpointType.Snapshot);
await fasterKV.TakeHybridLogCheckpointAsync(cfg.HlogType);

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

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

When it happens

Trigger: Calling TakeHybridLogCheckpointAsync/TryInitiateHybridLogCheckpoint with an undefined CheckpointType value (not FoldOver or Snapshot), e.g. from a mis-typed numeric cast.

Common situations: Same as full checkpoints: config-driven enum values, cross-version enum drift, deserialized values out of range.

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

• Unsupported full checkpoint type
• AsyncFlushPages(), error: %u
• Can spin-wait for commit (checkpoint completion) only if…
• Cannot recover from (
• Cannot use CompleteCheckpointAsync when using non-async…

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

Appendix: source

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

        /// 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 could initiate the checkpoint. Use CompleteCheckpointAsync to wait completion.</returns>
        public bool TryInitiateHybridLogCheckpoint(out Guid token, CheckpointType checkpointType, bool tryIncremental = false,
            long targetVersion = -1)
        {
            ISynchronizationTask backend;
            if (checkpointType == CheckpointType.FoldOver)
                backend = new FoldOverCheckpointTask();
            else if (checkpointType == CheckpointType.Snapshot)
            {
                if (tryIncremental && _lastSnapshotCheckpoint.info.guid != default && _lastSnapshotCheckpoint.info.finalLogicalAddress > hlog.FlushedUntilAddress && (hlog is not GenericAllocator<Key, Value>))
                    backend = new IncrementalSnapshotCheckpointTask();
                else
                    backend = new SnapshotCheckpointTask();
            }
            else
                throw new FasterException("Unsupported checkpoint type");

            var result = StartStateMachine(new HybridLogCheckpointStateMachine(backend, targetVersion));
            token = _hybridLogCheckpointToken;
            return result;
        }

        /// <summary>
        /// Take log-only checkpoint
        /// </summary>
        /// <param name="checkpointType">Checkpoint type</param>
        /// <param name="tryIncremental">For snapshot, try to store as incremental delta over last snapshot</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. 
        /// </param>
        /// <returns>

View on GitHub (pinned to 321d872eab)