microsoft/garnet · error · GarnetException

Invalid KeyMigrationStatus: {state}

Error message

Invalid KeyMigrationStatus: {state}

What it means

Thrown by CanAccessKey's status switch when a SketchStatus is not one of INITIALIZING, MIGRATED, TRANSMITTING, or DELETING. All four documented statuses are handled, so the default arm only fires for an invalid/out-of-range cast. It guards the per-key access decision during slot/key migration.

Source

Thrown at libs/cluster/Server/Migration/MigrateSessionKeyAccess.cs:59

            var state = SketchStatus.INITIALIZING;
            foreach (var migrateTask in migrateOperation)
            {
                if (migrateTask.sketch.Probe(key, out state))
                    goto found;
            }

            return true;

        found:
            // NOTE:
            // Caller responsible for spin-wait
            // Check definition of KeyMigrationStatus for more info
            return state switch
            {
                SketchStatus.INITIALIZING or SketchStatus.MIGRATED => true,// Both reads and write commands can access key if it exists
                SketchStatus.TRANSMITTING => readOnly, // If key exists read commands can access key but write commands will be delayed
                SketchStatus.DELETING => false, // Neither read or write commands can access key
                _ => throw new GarnetException($"Invalid KeyMigrationStatus: {state}")
            };
        }
    }
}

View on GitHub (pinned to 951b0fc683)

Solutions

1. Verify sketches are always constructed with Status = INITIALIZING and transitioned only through the defined statuses.
2. Ensure no sketch object is reused after its migration lifecycle ends.
3. Keep the switch exhaustive when SketchStatus is extended.

// Validate sketch status before access decision
if ((byte)state > (byte)SketchStatus.MIGRATED)
    throw new ArgumentOutOfRangeException(nameof(state), state, "Unknown SketchStatus");
return CanAccessKey(key, slot, readOnly);

When it happens

Trigger: Reading a SketchStatus field that holds a value outside 0..3 (uninitialized memory or an unsafe cast), or a new SketchStatus member added to the enum without updating this switch.

Common situations: Concurrent migration reset that leaves a sketch in a transient/garbage status; memory corruption or a stale sketch reused after migration completed.

Related errors

• MigrateSession Invalid TransferOption {transferOption}
• Invalid SETSLOT Operation
• Sketch size should be power of 2!
• invalid failover status
• Option {fileType} not supported

AI-assisted analysis of microsoft/garnet@951b0fc683 (2026-08-13). Data as JSON: /api/errors/4aa73622927fae08. Report an issue: GitHub.