What causes "Invalid Enum Argument" in microsoft/FASTER?

Serialize checkpoint/snapshot calls - never issue two state-machine operations concurrently.

microsoft/FASTER · error · FasterException

Invalid Enum Argument

Error message

Invalid Enum Argument

What it means

IndexSnapshotStateMachine.NextState advances the phases of an index snapshot (WAIT_FLUSH -> WAIT_INDEX_CHECKPOINT -> WAIT_INDEX_ONLY_CHECKPOINT -> REST). An unrecognized Phase falls into the default branch, which throws this exception. It indicates the snapshot state machine encountered a phase outside its defined transitions - an internal invariant violation.

Solutions

Serialize checkpoint/snapshot calls - never issue two state-machine operations concurrently.
Restart the process and retake the checkpoint.
Report a bug with repro details if the exception fires in a single-threaded checkpoint flow.

Example fix

// before
_ = faster.TakeIndexCheckpointAsync();
await faster.TakeCheckpointAsync(); // overlapping state machines
// after
await faster.TakeCheckpointAsync(); // one state machine at a time
await faster.TakeIndexCheckpointAsync();

Defensive patterns

Strategy: try-catch

Validate before calling

// Serialize checkpoint operations behind a semaphore
if (!await checkpointSemaphore.WaitAsync(0))
    throw new InvalidOperationException("A checkpoint/snapshot is already running.");

Try / catch

try
{
    await faster.TakeIndexCheckpointAsync();
}
catch (FasterException ex) when (ex.Message == "Invalid Enum Argument")
{
    logger.LogError(ex, "Index snapshot state machine corrupted; retake checkpoint after restart");
    throw;
}

Prevention

Issue one checkpoint/snapshot at a time; await each before the next.
Clean up partially written checkpoint directories after crashes.
Capture stack traces when this fires and report upstream.

When it happens

Trigger: Internal phase corruption while TakeIndexCheckpoint/TakeCheckpoint executes the index snapshot state machine; typically from concurrent state machine overlap or resuming corrupted checkpoint state after a crash.

Common situations: Calling snapshot/checkpoint operations concurrently on the same FASTER instance; recovering a checkpoint directory written by a crashed snapshot.

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/fdd8be7cfa87a63e. Report an issue: GitHub.

Appendix: source

Thrown at cs/src/core/Index/Synchronization/IndexSnapshotStateMachine.cs:126

        }

        /// <inheritdoc />
        public override SystemState NextState(SystemState start)
        {
            var result = SystemState.Copy(ref start);
            switch (start.Phase)
            {
                case Phase.REST:
                    result.Phase = Phase.PREP_INDEX_CHECKPOINT;
                    break;
                case Phase.PREP_INDEX_CHECKPOINT:
                    result.Phase = Phase.WAIT_INDEX_ONLY_CHECKPOINT;
                    break;
                case Phase.WAIT_INDEX_ONLY_CHECKPOINT:
                    result.Phase = Phase.REST;
                    break;
                default:
                    throw new FasterException("Invalid Enum Argument");
            }

            return result;
        }
    }
}

View on GitHub (pinned to 321d872eab)