microsoft/FASTER · critical · FasterException

Unexpected entry type

Error message

Unexpected entry type

What it means

While replaying the allocator's (delta log / checkpoint) entries during recovery, FASTER switches on each entry's type; the default arm throws FasterException("Unexpected entry type") because entry types are an internal enum and any value outside the known set means the log is corrupt or was written by an incompatible FASTER version.

Solutions

  1. Verify the log/checkpoint files were produced by the same FASTER version you are recovering with; align versions if not.
  2. If files are corrupt, discard and recreate the log/checkpoint directory (accepting data loss) or restore from a known-good checkpoint.
  3. Enable/check device-level integrity (checksums, proper flush/fsync) to prevent torn writes, and rerun recovery from an earlier valid checkpoint.

Example fix

// before
// recovering logs written by FASTER 2.x with a 3.x binary
// after
// use the matching FASTER version to recover, or start fresh:
// delete CheckpointDir/LogDir contents and re-initialize the store
Defensive patterns

Strategy: try-catch

Validate before calling

// preflight: verify checkpoint dir exists and FASTER version matches the one that wrote the logs
if (!Directory.Exists(checkpointDir) || !VersionMatch(writingVersion, currentVersion)) throw new InvalidOperationException("Checkpoint/log files incompatible with this FASTER version");

Try / catch

try { store.Recover(recoverTo); } catch (FasterException) { /* fall back to previous checkpoint or reinitialize the log */ }

Prevention

When it happens

Trigger: Recovering a hybrid log/checkpoint whose delta or checkpoint metadata contains an entry type byte not recognized by the current code — corrupted log files, truncation/torn writes, or log files produced by a different FASTER version with different entry-type encoding.

Common situations: Crash mid-write leaving partially written delta/checkpoint logs; manually copying checkpoint files between deployments with different FASTER versions; disk corruption of log devices.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at cs/src/core/Allocator/AllocatorBase.cs:608

                        {
                            // Only read metadata if we need to stop at a specific version
                            var 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) return;
                        }

                        break;
                    default:
                        throw new FasterException("Unexpected entry type");

                }
            }
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        internal void MarkPage(long logicalAddress, long version)
        {
            var offset = (logicalAddress >> LogPageSizeBits) % BufferSize;
            if (PageStatusIndicator[offset].Dirty < version)
                PageStatusIndicator[offset].Dirty = version;
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        internal void MarkPageAtomic(long logicalAddress, long version)
        {
            var offset = (logicalAddress >> LogPageSizeBits) % BufferSize;
            Utility.MonotonicUpdate(ref PageStatusIndicator[offset].Dirty, version, out _);

View on GitHub (pinned to 321d872eab)