microsoft/garnet · critical · Exception

invalid metadata length: {hlri.cookie.Length} < 12

Error message

invalid metadata length: {hlri.cookie.Length} < 12

What it means

Thrown during legacy single-log cookie deserialization when the cookie is at least 4 bytes but fewer than 12, too small to read the 8-byte recoveredSafeAofAddress long that follows the 4-byte size prefix. Like error 29 it signals a corrupt or version-mismatched checkpoint metadata blob, just one that passed the first length check.

Source

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

        /// <param name="recoveredReplicationId"></param>
        /// <exception cref="Exception"></exception>
        public unsafe void GetCheckpointCookieMetadata(Guid logToken, ref AofAddress recoveredSafeAofAddress, out string recoveredReplicationId)
        {
            var metadata = GetLogCheckpointMetadata(logToken);
            var hlri = ConvertMetadata(metadata);

            recoveredReplicationId = null;
            if (RecoveredSafeAofAddress.Length == 1)
            {
                // Legacy single log deserialization for backward compatibility
                var bytesRead = sizeof(int);
                fixed (byte* ptr = hlri.cookie)
                {
                    if (hlri.cookie.Length < 4) throw new Exception($"invalid metadata length: {hlri.cookie.Length} < 4");
                    var cookieSize = *(int*)ptr;
                    bytesRead += cookieSize;

                    if (hlri.cookie.Length < 12) throw new Exception($"invalid metadata length: {hlri.cookie.Length} < 12");
                    recoveredSafeAofAddress[0] = *(long*)(ptr + 4);

                    if (hlri.cookie.Length < 52) throw new Exception($"invalid metadata length: {hlri.cookie.Length} < 52");
                    recoveredReplicationId = Encoding.ASCII.GetString(ptr + 12, 40);
                }
            }
            else
            {
                // Multi-log cookie
                using var ms = new MemoryStream(hlri.cookie);
                using var reader = new BinaryReader(ms, Encoding.ASCII);
                recoveredReplicationId = reader.ReadInt32() > 0 ? reader.ReadString() : null;
                recoveredSafeAofAddress = AofAddress.Deserialize(reader);
                reader.Dispose();
                ms.Dispose();
            }
        }

View on GitHub (pinned to 951b0fc683)

Solutions

1. Discard the affected checkpoint and recover from a valid full checkpoint.
2. Confirm the checkpoint was produced by a compatible Garnet version.
3. Re-run a full checkpoint after any version upgrade to rewrite cookies in the current format.

// Validate cookie length for the safeAofAddress read
if (hlri.cookie == null || hlri.cookie.Length < 12)
    throw new InvalidDataException($"Checkpoint cookie too short ({hlri?.cookie?.Length ?? -1} bytes) for AOF address; corrupt or incompatible checkpoint");

try { manager.GetCheckpointCookieMetadata(logToken, ref addr, out var id); }
catch (Exception ex) when (ex.Message.Contains("invalid metadata length"))
{
    logger?.LogError(ex, "Corrupt/incompatible checkpoint cookie for log {logToken}", logToken);
    // recover from a valid full checkpoint
}

When it happens

Trigger: GetCheckpointCookieMetadata on a cookie between 4 and 11 bytes long — a malformed or truncated checkpoint produced by an incompatible/crashed write.

Common situations: Same family as error 29: cross-version checkpoint incompatibility, truncated checkpoint after a crash, or on-disk metadata corruption.

Related errors

• invalid metadata length: {hlri.cookie.Length} < 4
• Option {fileType} not supported
• Checkpoint history unavailable, need full checkpoint for {en
• Failed to validate main store metadata at insertion
• RetrieveCheckpointFile: unexpected state{retStateType}

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