microsoft/garnet · error · Exception

RetrieveCheckpointFile: unexpected state{retStateType}

Error message

RetrieveCheckpointFile: unexpected state{retStateType}

What it means

Thrown by GarnetClusterCheckpointManager.GetDevice when retStateType is not STORE_INDEX, STORE_SNAPSHOT, or STORE_SNAPSHOT_OBJ. The device factory only knows how to open devices for those three checkpoint file kinds; any other CheckpointFileType is a programming error in the recovery/checkpoint-load path.

Source

Thrown at libs/cluster/Server/Replication/GarnetClusterCheckpointManager.cs:65

            => checkpointVersionShiftStart?.Invoke(isMainStore, oldVersion, newVersion, isStreaming);

        public override void CheckpointVersionShiftEnd(long oldVersion, long newVersion, bool isStreaming)
            => checkpointVersionShiftEnd?.Invoke(isMainStore, oldVersion, newVersion, isStreaming);

        public void DeleteLogCheckpoint(Guid logToken)
            => deviceFactory.Delete(checkpointNamingScheme.LogCheckpointBase(logToken));

        public void DeleteIndexCheckpoint(Guid indexToken)
            => deviceFactory.Delete(checkpointNamingScheme.IndexCheckpointBase(indexToken));

        public IDevice GetDevice(CheckpointFileType retStateType, Guid fileToken)
        {
            var device = retStateType switch
            {
                CheckpointFileType.STORE_INDEX => GetIndexDevice(fileToken),
                CheckpointFileType.STORE_SNAPSHOT => GetSnapshotLogDevice(fileToken),
                CheckpointFileType.STORE_SNAPSHOT_OBJ => GetSnapshotObjectLogDevice(fileToken),
                _ => throw new Exception($"RetrieveCheckpointFile: unexpected state{retStateType}")
            };
            return device;
        }

        #region ICheckpointManager

        private HybridLogRecoveryInfo ConvertMetadata(byte[] checkpointMetadata)
        {
            HybridLogRecoveryInfo recoveryInfo = new();

            // Try to parse new format where cookie is embedded inside the HybridLogRecoveryInfo
            try
            {
                using var s = new StreamReader(new MemoryStream(checkpointMetadata));
                recoveryInfo.Initialize(s);
            }
            catch (Exception ex)
            {

View on GitHub (pinned to 951b0fc683)

Solutions

Use GetDevice only for STORE_INDEX, STORE_SNAPSHOT, STORE_SNAPSHOT_OBJ.
For hybrid-log devices, use the dedicated hlog device accessor rather than this dispatch method.
Extend the switch when a new file type needs device access.

Defensive patterns

Strategy: validation

Validate before calling

// Only request devices for supported file types
if (fileType is not (CheckpointFileType.STORE_INDEX or CheckpointFileType.STORE_SNAPSHOT or CheckpointFileType.STORE_SNAPSHOT_OBJ))
    throw new ArgumentOutOfRangeException(nameof(fileType), fileType, "GetDevice supports index/snapshot file types only");
return manager.GetDevice(fileType, token);

Prevention

Use GetDevice only for index/snapshot file types; use dedicated accessors for hlog devices.
Extend the switch when new file types require device access.
Document which file types each device accessor supports.

When it happens

Trigger: Requesting a device for a STORE_HLOG, STORE_HLOG_OBJ, STORE_RANGEINDEX_*, NONE, or out-of-range file type through this GetDevice method.

Common situations: A recovery path that requests the hlog device via GetDevice instead of the dedicated hlog device accessor; new checkpoint file types added without a GetDevice arm.

Related errors

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