microsoft/garnet · critical · GarnetException

Unknown AOF header operation type {header.opType}

Error message

Unknown AOF header operation type {header.opType}

What it means

Thrown by AofProcessor.ProcessAofRecordInternal in the operation-type dispatch switch when header.opType does not match any known AofEntryType (StoreUpsert, StoreRMW, StoreDelete, ObjectStoreUpsert, ObjectStoreRMW, ObjectStoreDelete, and the Unified* variants). This means the entry's operation-type byte is unrecognized — indicating corruption or data from a newer version that added a new entry type.

Source

Thrown at libs/server/AOF/AofProcessor.cs:502

                    ObjectStoreRMW(preparedParameters, objectContext, ref replayContext.parseState, bufferPtr, bufferLength, legacyCmdFormat);
                    break;
                case AofEntryType.ObjectStoreDelete:
                    ObjectStoreDelete(preparedParameters, objectContext);
                    break;
                case AofEntryType.UnifiedStoreStringUpsert:
                    UnifiedStoreStringUpsert(preparedParameters, unifiedContext, ref replayContext.parseState, bufferPtr, bufferLength, legacyCmdFormat);
                    break;
                case AofEntryType.UnifiedStoreRMW:
                    UnifiedStoreRMW(preparedParameters, unifiedContext, ref replayContext.parseState, bufferPtr, bufferLength, legacyCmdFormat);
                    break;
                case AofEntryType.UnifiedStoreObjectUpsert:
                    UnifiedStoreObjectUpsert(preparedParameters, unifiedContext, storeWrapper.GarnetObjectSerializer, bufferPtr, bufferLength);
                    break;
                case AofEntryType.UnifiedStoreDelete:
                    UnifiedStoreDelete(preparedParameters, unifiedContext, activeVectorManager, replayContext.respServerSession.storageSession);
                    break;
                default:
                    throw new GarnetException($"Unknown AOF header operation type {header.opType}");
            }

            return true;
        }

        static void StoreUpsert<TStringContext>(PreparedParameters preparedParameters, TStringContext stringContext, ref SessionParseState parseState, bool legacyCmdFormat)
            where TStringContext : ITsavoriteContext<FixedSpanByteKey, StringInput, StringOutput, long, MainSessionFunctions, StoreFunctions, StoreAllocator>
        {
            var curr = preparedParameters.PayloadPtr;
            var value = PinnedSpanByte.FromLengthPrefixedPinnedPointer(curr);
            curr += value.TotalSize;

            var stringInput = new StringInput { parseState = parseState };
            _ = stringInput.DeserializeFrom(curr);
            if (legacyCmdFormat)
                stringInput.header.cmd = LegacyRespCommand.FromV3(stringInput.header.cmd);

            StringOutput output = default;

View on GitHub (pinned to 951b0fc683)

Solutions

1. Ensure the replaying Garnet build is >= the build that wrote the AOF (new AofEntryType values are additive).
2. Restore the data directory from a clean checkpoint+AOF backup.
3. If reproducible with known-good data, file a Garnet issue with the opType value and the entry hexdump.
4. Verify storage media health (check dmesg / SMART for disk errors).

try { aofProcessor.ProcessAofRecordInternal(...); }
catch (GarnetException ex) when (ex.Message.Contains("Unknown AOF header operation type"))
{
    logger.LogCritical(ex, "Unrecognized AOF opType during replay; data may be from a newer/corrupt source.");
    throw;
}

When it happens

Trigger: During replay, the opType field of an AOF entry falls through all enumerated cases. This can happen if the AOF was written by a newer Garnet version that introduced a new AofEntryType, or if the entry is corrupted so the opType byte is garbage.

Common situations: Version skew between the writer and the replayer; bit-rot on the AOF device; a bug in serialization that wrote an invalid opType.

Related errors

• Type not supported {headerType}
• Unsupported header type: {headerType}
• Replay header type {replayHeaderType} not supported!
• Unsupported AOF header version {header.aofHeaderVersion}; th
• Failed to acquire inProgress lock at {nameof(PreSingleKeyCon

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