{"record":{"id":"5edf6c1878d248d9","repo":"microsoft/FASTER","slug":"invalid-index-commit-metadata-for-id","errorCode":null,"errorMessage":"Invalid index commit metadata for ID ","messagePattern":"Invalid index commit metadata for ID ","errorType":"exception","errorClass":"FasterException","httpStatus":null,"severity":"error","filePath":"cs/src/core/Index/Common/Contexts.cs","lineNumber":825,"sourceCode":"            value = reader.ReadLine();\n            startLogicalAddress = long.Parse(value);\n\n            value = reader.ReadLine();\n            finalLogicalAddress = long.Parse(value);\n\n            if (cversion != CheckpointVersion)\n                throw new FasterException(\"Invalid version\");\n\n            if (checksum != Checksum())\n                throw new FasterException(\"Invalid checksum for checkpoint\");\n        }\n\n        public void Recover(Guid guid, ICheckpointManager checkpointManager)\n        {\n            this.token = guid;\n            var metadata = checkpointManager.GetIndexCheckpointMetadata(guid);\n            if (metadata == null)\n                throw new FasterException(\"Invalid index commit metadata for ID \" + guid.ToString());\n            using (StreamReader s = new(new MemoryStream(metadata)))\n                Initialize(s);\n        }\n\n        public readonly byte[] ToByteArray()\n        {\n            using (MemoryStream ms = new())\n            {\n                using (StreamWriter writer = new(ms))\n                {\n                    writer.WriteLine(CheckpointVersion); // checkpoint version\n                    writer.WriteLine(Checksum()); // checksum\n\n                    writer.WriteLine(token);\n                    writer.WriteLine(table_size);\n                    writer.WriteLine(num_ht_bytes);\n                    writer.WriteLine(num_ofb_bytes);\n                    writer.WriteLine(num_buckets);","sourceCodeStart":807,"sourceCodeEnd":843,"githubUrl":"https://github.com/microsoft/FASTER/blob/321d872eabda6a0345c8bd76419f89723ed864ae/cs/src/core/Index/Common/Contexts.cs#L807-L843","documentation":"IndexCheckpointMetadata.Recover throws when checkpointManager.GetIndexCheckpointMetadata(guid) returns null, i.e., no index checkpoint metadata exists for the given token. This usually means the token is invalid, the checkpoint was deleted, or the recovery call was made before a matching checkpoint was taken.","triggerScenarios":"Calling Recover with a Guid token that does not exist in the checkpoint store: token from an index checkpoint passed where a hybrid-log checkpoint is expected, checkpoint already purged by retention/cleanup, or recovery attempted before any checkpoint completed.","commonSituations":"Persisting the wrong token (e.g., storing _hybridLogCheckpointToken but calling index recovery); log/checkpoint retention deleting old checkpoints; environment mismatch (recovery against a different container's checkpoint store); taking only a hybrid-log checkpoint but trying to recover the index too.","solutions":["Verify the Guid matches an existing index checkpoint in the checkpoint manager's store","Take a full (index + hybrid-log) checkpoint so both tokens exist, then recover with the full-checkpoint token","Check checkpoint retention/purge policy isn't deleting the checkpoint before recovery","Confirm you're pointing at the same checkpoint directory/container used at checkpoint time"],"exampleFix":"// before: recovering index from a hybrid-log-only checkpoint token\nfasterKV.Recover(hybridLogToken);\n// after: use the token from TakeFullCheckpointAsync / GetIndexCheckpointToken\n(long token, _) = await fasterKV.TakeFullCheckpointAsync();\nfasterKV.Recover(new Guid(token.ToString()));","handlingStrategy":"try-catch","validationCode":"// Ensure the token came from a full checkpoint or an index checkpoint specifically\nif (token == default || !knownIndexCheckpointTokens.Contains(token))\n    throw new InvalidOperationException($\"No index checkpoint known for token {token}\");","typeGuard":null,"tryCatchPattern":"try { fasterKV.Recover(token); }\ncatch (FasterException ex) when (ex.Message.StartsWith(\"Invalid index commit metadata for ID\"))\n{\n    // token is missing: enumerate available checkpoints and fail fast with a clear message\n    throw new InvalidOperationException($\"Index checkpoint {token} not found; check retention policy and checkpoint directory\");\n}","preventionTips":["Persist tokens from TakeFullCheckpointAsync (not just hybrid-log tokens) with each checkpoint","Configure checkpoint manager retention long enough to cover crash-recovery needs","Verify the recovery process uses the same checkpoint directory/container as the writer","Take full checkpoints periodically so index metadata always exists"],"tags":["checkpoint","recovery","not-found","token"],"backgroundTag":"entity-not-found","analyzedSha":"321d872eabda6a0345c8bd76419f89723ed864ae","analyzedAt":"2026-09-15T22:18:00.693Z","contentChangedAt":"2026-09-15T22:18:00.693Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}