microsoft/FASTER · error · FasterException

Invalid Enum Argument

Error message

Invalid Enum Argument

What it means

VersionChangeStateMachine.NextState computes the next state of the FASTER version change protocol (used by ShiftLogicalAddress / blocking version management). Its switch advances PREPARE -> IN_PROGRESS -> REST; any other Phase hits the default branch and throws this exception. This is an internal exhaustive-switch guard, not a validation of user input.

Solutions

1. Do not mix manual version management calls with checkpoint/snapshot state machines running concurrently; serialize them.
2. Restart the process to restore the REST phase, then retry the version change.
3. Report a FASTER bug with the exact call sequence if it reproduces deterministically.

Example fix

// before
faster.NextVersion();
await faster.TakeCheckpointAsync(); // concurrent state machines
// after
faster.NextVersion();
faster.CompletePending();
await faster.TakeCheckpointAsync(); // after version change settles

// Do not advance versions while a checkpoint state machine is running
if (checkpointInProgress) throw new InvalidOperationException("Version change conflicts with active checkpoint.");

try
{
    faster.NextVersion();
}
catch (FasterException ex) when (ex.Message == "Invalid Enum Argument")
{
    logger.LogError(ex, "Version change state machine in unknown phase; restart required");
    throw;
}

When it happens

Trigger: Phase corruption during a version change operation - e.g. interleaving blocking version advancement (NextVersion/ShiftLogicalAddress) with checkpoints or snapshots, or resuming with corrupted versionInfo state after a crash.

Common situations: Application code manually driving version changes while background checkpointing runs; failed prior version change leaving versionInfo in a non-standard phase.

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

• Invalid Enum Argument
• Invalid Enum Argument
• Out of order message within session
• Unexpected status of SubscribeKV
• Cannot use BlittableParameterSerializer with non-blittable…

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

Appendix: source

Thrown at cs/src/core/Index/Synchronization/VersionChangeStateMachine.cs:154

        /// <inheritdoc />
        public override SystemState NextState(SystemState start)
        {
            var nextState = SystemState.Copy(ref start);
            switch (start.Phase)
            {
                case Phase.REST:
                    nextState.Phase = Phase.PREPARE;
                    break;
                case Phase.PREPARE:
                    nextState.Phase = Phase.IN_PROGRESS;
                    SetToVersion(targetVersion == -1 ? start.Version + 1 : targetVersion);
                    nextState.Version = ToVersion();
                    break;
                case Phase.IN_PROGRESS:
                    nextState.Phase = Phase.REST;
                    break;
                default:
                    throw new FasterException("Invalid Enum Argument");
            }

            return nextState;
        }
    }
}

View on GitHub (pinned to 321d872eab)