microsoft/FASTER · error · FasterException

Invalid version

Error message

Invalid version

What it means

FasterKV throws this during index checkpoint recovery when the checkpoint's stored CheckpointVersion does not match the CheckpointVersion this build of the library expects. It guards against loading a checkpoint file written by an incompatible (older or newer) version of the engine. Recovery is aborted before any state is deserialized.

Solutions

1. Recreate the checkpoint using the current library version (take a fresh checkpoint under the deployed binary)
2. Restore the original binary version that produced the checkpoint, recover the data, re-checkpoint, then upgrade
3. Verify the checkpoint metadata file is complete and not corrupted or hand-edited (first lines must include the checkpoint version)

Example fix

// before: opening old checkpoint with upgraded library
fasterKV.Recover(checkpointToken);
// after: migrate by re-checkpointing with the old version first
// (run with old lib): await fasterKV.TakeFullCheckpointAsync();
// (run with new lib): rebuild from logs or re-checkpoint, then:
fasterKV.Recover(newToken);

// Before recovering, ensure the checkpoint came from the same library version
// Store your application/library version alongside tokens:
if (savedLibraryVersion != typeof(FasterKV<,>).Assembly.GetName().Version)
    throw new InvalidOperationException("Checkpoint was written by an incompatible FASTER version; re-checkpoint before upgrading");

try { fasterKV.Recover(token); }
catch (FasterException ex) when (ex.Message == "Invalid version")
{
    // fall back to rebuilding from log or restoring compatible binary
}

When it happens

Trigger: Calling Recover/RecoverIndexCheckpoint (directly or via a recovery/token-based open) with a checkpoint whose metadata file was written by a different FASTER version, or with a checkpoint metadata stream whose 'cversion' line was altered or truncated.

Common situations: Upgrading the FASTER library (or the .NET runtime assembly version) and then trying to open an index checkpoint created by the previous version; copying checkpoint files across deployments built from different source trees; hand-editing or partially-written checkpoint metadata.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Unable to set first valid segment to
• Unable to set last valid segment to
• Invalid checkpoint version
• Unable to find valid HybridLog token
• Recovering to a specific version within a token is only…

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

Appendix: source

Thrown at cs/src/core/Index/Common/Contexts.cs:814

            table_size = long.Parse(value);

            value = reader.ReadLine();
            num_ht_bytes = ulong.Parse(value);

            value = reader.ReadLine();
            num_ofb_bytes = ulong.Parse(value);

            value = reader.ReadLine();
            num_buckets = int.Parse(value);

            value = reader.ReadLine();
            startLogicalAddress = long.Parse(value);

            value = reader.ReadLine();
            finalLogicalAddress = long.Parse(value);

            if (cversion != CheckpointVersion)
                throw new FasterException("Invalid version");

            if (checksum != Checksum())
                throw new FasterException("Invalid checksum for checkpoint");
        }

        public void Recover(Guid guid, ICheckpointManager checkpointManager)
        {
            this.token = guid;
            var metadata = checkpointManager.GetIndexCheckpointMetadata(guid);
            if (metadata == null)
                throw new FasterException("Invalid index commit metadata for ID " + guid.ToString());
            using (StreamReader s = new(new MemoryStream(metadata)))
                Initialize(s);
        }

        public readonly byte[] ToByteArray()
        {
            using (MemoryStream ms = new())

View on GitHub (pinned to 321d872eab)