microsoft/FASTER · error · FasterException

Unexpected entry type

Error message

Unexpected entry type

What it means

While scanning the delta log in GetLogCheckpointMetadata, each entry carries an entry type (e.g. CHECKPOINT_METADATA, another known type, or unknown). The switch's default arm throws FasterException("Unexpected entry type") when an entry with an unrecognized DeltaLogEntryType is encountered. This indicates a corrupt or foreign delta log record that the current code does not know how to interpret.

Solutions

1. Restore the checkpoint files from a known-good backup; the delta log is corrupt or unreadable.
2. Recover from the base (full) checkpoint metadata instead of scanning the delta log (scanDelta=false or recoverTo the last full version).
3. Ensure the reading library version matches the version that wrote the checkpoint; version skew can introduce unknown entry types.
4. Do not hand-edit or share delta log files across incompatible processes.

Example fix

// before
var meta = checkpointManager.GetLogCheckpointMetadata(token, deltaLog, scanDelta: true, recoverTo: version);

// after
var meta = checkpointManager.GetLogCheckpointMetadata(token, deltaLog, scanDelta: false, recoverTo: -1); // read full metadata, skip risky delta scan
if (meta == null) throw new InvalidOperationException($"No metadata for checkpoint {token}");

try { meta = manager.GetLogCheckpointMetadata(token, deltaLog, scanDelta: true, recoverTo); } catch (FasterException ex) when (ex.Message == "Unexpected entry type") { meta = manager.GetLogCheckpointMetadata(token, deltaLog, scanDelta: false, recoverTo: -1); }

When it happens

Trigger: Calling GetLogCheckpointMetadata (directly or via Recover with scanDelta=true) when the delta log contains an entry whose type is not one of the handled DeltaLogEntryType values, hitting the switch default.

Common situations: Delta log corrupted by a crash mid-write; delta log written by a different (newer/older) library version with extra entry types; reading a device file that is not actually this format.

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

• Metadata of size does not fit in delta log space of size
• Checksum failed for read
• Uninitialized page found during scan at page
• Invalid length of record found
• Invalid checksum found during scan, skipping

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

Appendix: source

Thrown at cs/src/core/Index/CheckpointManagement/DeviceLogCommitCheckpointManager.cs:314

                            // consider only metadata records
                            continue;
                        case DeltaLogEntryType.CHECKPOINT_METADATA:
                            metadata = new byte[entryLength];
                            unsafe
                            {
                                fixed (byte* m = metadata)
                                    Buffer.MemoryCopy((void*)physicalAddress, m, entryLength, entryLength);
                            }
                            HybridLogRecoveryInfo recoveryInfo = new();
                            using (StreamReader s = new(new MemoryStream(metadata)))
                            {
                                recoveryInfo.Initialize(s);
                                // Finish recovery if only specific versions are requested
                                if (recoveryInfo.version == recoverTo || recoveryInfo.version < recoverTo && recoveryInfo.nextVersion > recoverTo) goto LoopEnd;
                            }
                            continue;
                        default:
                            throw new FasterException("Unexpected entry type");
                    }
                LoopEnd:
                    break;
                }
                if (metadata != null) return metadata;

            }

            var device = deviceFactory.Get(checkpointNamingScheme.LogCheckpointMetadata(logToken));

            ReadInto(device, 0, out byte[] writePad, sizeof(int));
            int size = BitConverter.ToInt32(writePad, 0);

            byte[] body;
            if (writePad.Length >= size + sizeof(int))
                body = writePad;
            else
                ReadInto(device, 0, out body, size + sizeof(int));

View on GitHub (pinned to 321d872eab)