microsoft/garnet · critical · GarnetException

Unsupported AOF header version {header.aofHeaderVersion}; th

Error message

Unsupported AOF header version {header.aofHeaderVersion}; this build supports up to version {AofHeader.MaxSupportedAofHeaderVersion}. The data may have been written by a newer Garnet version.

What it means

Thrown by AofProcessor.ProcessAofRecordInternal when an AOF entry's aofHeaderVersion field exceeds AofHeader.MaxSupportedAofHeaderVersion (currently 4). This is an explicit forward-compatibility guard: rather than silently misinterpreting an entry written by a newer Garnet format, the build fails fast. The message tells the operator the data came from a newer version.

Source

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

        /// <summary>
        /// Process AOF record internal
        /// NOTE: This method is shared between recover replay and replication replay
        /// </summary>
        /// <param name="virtualSublogIdx"></param>
        /// <param name="ptr"></param>
        /// <param name="length"></param>
        /// <param name="asReplica"></param>
        /// <param name="isCheckpointStart"></param>
        /// <param name="logAddressSequenceNumber"></param>
        public void ProcessAofRecordInternal(int virtualSublogIdx, byte* ptr, int length, bool asReplica, out bool isCheckpointStart, long logAddressSequenceNumber = 0)
        {
            var header = *(AofHeader*)ptr;

            // Reject entries written by a newer Garnet version (higher AOF header version) rather than
            // silently mis-interpreting them under this version's format.
            if (header.aofHeaderVersion > AofHeader.MaxSupportedAofHeaderVersion)
                throw new GarnetException($"Unsupported AOF header version {header.aofHeaderVersion}; this build supports up to version {AofHeader.MaxSupportedAofHeaderVersion}. The data may have been written by a newer Garnet version.");

            var replayContext = aofReplayCoordinator.GetReplayContext(virtualSublogIdx);
            isCheckpointStart = false;

            // StoreRMW can queue VADDs onto different threads
            // but everything else needs to WAIT for those to complete
            // otherwise we might loose consistency
            if (header.opType != AofEntryType.StoreRMW)
            {
                activeVectorManager.WaitForVectorOperationsToComplete();
            }

            // Handle transactions
            if (aofReplayCoordinator.AddOrReplayTransactionOperation(virtualSublogIdx, ptr, length, asReplica, logAddressSequenceNumber))
                return;

            switch (header.opType)
            {

View on GitHub (pinned to 951b0fc683)

Solutions

Upgrade the Garnet binary to a version >= the one that wrote the AOF (the message states the detected version).
If a rollback is mandatory, delete the AOF and checkpoint files and restart from an empty data directory (accepting data loss).
In a replication topology, ensure all nodes run the same Garnet version.
Never downgrade a running cluster; drain and clear data directories first.

Defensive patterns

Strategy: validation

Validate before calling

// Before recovery, compare the on-disk AOF header version to the build's max supported version
// This is internal, but operators can guard by ensuring binary version >= data version.
// Check Garnet version in release notes and do not downgrade against existing data.

Try / catch

try { aofProcessor.ProcessAofRecordInternal(...); }
catch (GarnetException ex) when (ex.Message.Contains("Unsupported AOF header version"))
{
    logger.LogCritical("AOF data written by a newer Garnet version; upgrade the binary before replaying.");
    throw;
}

Prevention

Never downgrade Garnet against an existing data directory without clearing it.
Keep all cluster nodes on the same version.
Before upgrading, snapshot the data directory so rollback can use the older data format.

When it happens

Trigger: Starting an older Garnet build against an AOF and/or checkpoint that was written by a newer Garnet build (one that incremented AofHeaderVersion). The version check fires on the first entry read during recovery or replication replay.

Common situations: Rolling back a Garnet upgrade without clearing the data directory; pointing a replica running an older build at a primary running a newer build; mixing binaries across nodes in a cluster.

Related errors

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