{"record":{"id":"940c9a8d161c878d","repo":"microsoft/garnet","slug":"unsupported-aof-header-version-header-aofheaderve","errorCode":null,"errorMessage":"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.","messagePattern":"Unsupported AOF header version (.+?); this build supports up to version (.+?)\\. The data may have been written by a newer Garnet version\\.","errorType":"exception","errorClass":"GarnetException","httpStatus":null,"severity":"critical","filePath":"libs/server/AOF/AofProcessor.cs","lineNumber":240,"sourceCode":"\n        /// <summary>\n        /// Process AOF record internal\n        /// NOTE: This method is shared between recover replay and replication replay\n        /// </summary>\n        /// <param name=\"virtualSublogIdx\"></param>\n        /// <param name=\"ptr\"></param>\n        /// <param name=\"length\"></param>\n        /// <param name=\"asReplica\"></param>\n        /// <param name=\"isCheckpointStart\"></param>\n        /// <param name=\"logAddressSequenceNumber\"></param>\n        public void ProcessAofRecordInternal(int virtualSublogIdx, byte* ptr, int length, bool asReplica, out bool isCheckpointStart, long logAddressSequenceNumber = 0)\n        {\n            var header = *(AofHeader*)ptr;\n\n            // Reject entries written by a newer Garnet version (higher AOF header version) rather than\n            // silently mis-interpreting them under this version's format.\n            if (header.aofHeaderVersion > AofHeader.MaxSupportedAofHeaderVersion)\n                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.\");\n\n            var replayContext = aofReplayCoordinator.GetReplayContext(virtualSublogIdx);\n            isCheckpointStart = false;\n\n            // StoreRMW can queue VADDs onto different threads\n            // but everything else needs to WAIT for those to complete\n            // otherwise we might loose consistency\n            if (header.opType != AofEntryType.StoreRMW)\n            {\n                activeVectorManager.WaitForVectorOperationsToComplete();\n            }\n\n            // Handle transactions\n            if (aofReplayCoordinator.AddOrReplayTransactionOperation(virtualSublogIdx, ptr, length, asReplica, logAddressSequenceNumber))\n                return;\n\n            switch (header.opType)\n            {","sourceCodeStart":222,"sourceCodeEnd":258,"githubUrl":"https://github.com/microsoft/garnet/blob/951b0fc6838721f89d102c2bbe1b914e8d39d700/libs/server/AOF/AofProcessor.cs#L222-L258","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Before recovery, compare the on-disk AOF header version to the build's max supported version\n// This is internal, but operators can guard by ensuring binary version >= data version.\n// Check Garnet version in release notes and do not downgrade against existing data.","typeGuard":null,"tryCatchPattern":"try { aofProcessor.ProcessAofRecordInternal(...); }\ncatch (GarnetException ex) when (ex.Message.Contains(\"Unsupported AOF header version\"))\n{\n    logger.LogCritical(\"AOF data written by a newer Garnet version; upgrade the binary before replaying.\");\n    throw;\n}","preventionTips":["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."],"tags":["aof","version-mismatch","compatibility","replay"],"backgroundTag":null,"analyzedSha":"951b0fc6838721f89d102c2bbe1b914e8d39d700","analyzedAt":"2026-08-13T19:01:32.939Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}