{"record":{"id":"6ef4a1934e2fc9e7","repo":"aeron-io/aeron","slug":"invalid-newleadershipterm-this-appendposition-appendposition","errorCode":null,"errorMessage":"invalid newLeadershipTerm - this.appendPosition=${appendPosition} < termBaseLogPosition=${termBaseLogPosition} and nextLeadershipTermId=${nextLeadershipTermId}, logLeadershipTermId=${logLeadershipTermId}, nextTermBaseLogPosition=${nextTermBaseLogPosition}, nextLogPosition=${nextLogPosition}, leadershipTermId=${leadershipTermId}, termBaseLogPosition=${termBaseLogPosition}, logPosition=${logPosition}, commitPosition=${commitPosition}, leaderRecordingId=${leaderRecordingId}, leaderMemberId=${leaderMemberId}, logSessionId=${logSessionId}, isStartup=${isStartup}","messagePattern":"invalid newLeadershipTerm - this\\.appendPosition=(.+?) < termBaseLogPosition=(.+?) and nextLeadershipTermId=(.+?), logLeadershipTermId=(.+?), nextTermBaseLogPosition=(.+?), nextLogPosition=(.+?), leadershipTermId=(.+?), termBaseLogPosition=(.+?), logPosition=(.+?), commitPosition=(.+?), leaderRecordingId=(.+?), leaderMemberId=(.+?), logSessionId=(.+?), isStartup=(.+?)","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"critical","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/Election.java","lineNumber":499,"sourceCode":"                            // is already known. We could look it up from the recording log only to write\n                            // it back again...\n                            replicationTermBaseLogPosition = NULL_VALUE;\n                            state(FOLLOWER_LOG_REPLICATION, nowNs(ctx), \"\");\n                        }\n                        else if (appendPosition == nextTermBaseLogPosition)\n                        {\n                            if (NULL_POSITION != nextLogPosition)\n                            {\n                                replicationLeadershipTermId = nextLeadershipTermId;\n                                replicationStopPosition = nextLogPosition;\n                                replicationTermBaseLogPosition = nextTermBaseLogPosition;\n                                state(FOLLOWER_LOG_REPLICATION, nowNs(ctx), \"\");\n                            }\n                        }\n                    }\n                    else\n                    {\n                        throw new ClusterException(\n                            \"invalid newLeadershipTerm - this.appendPosition=\" + appendPosition +\n                            \" < termBaseLogPosition=\" + termBaseLogPosition +\n                            \" and nextLeadershipTermId=\" + nextLeadershipTermId +\n                            \", logLeadershipTermId=\" + logLeadershipTermId +\n                            \", nextTermBaseLogPosition=\" + nextTermBaseLogPosition +\n                            \", nextLogPosition=\" + nextLogPosition +\n                            \", leadershipTermId=\" + leadershipTermId +\n                            \", termBaseLogPosition=\" + termBaseLogPosition +\n                            \", logPosition=\" + logPosition +\n                            \", commitPosition=\" + commitPosition +\n                            \", leaderRecordingId=\" + leaderRecordingId +\n                            \", leaderMemberId=\" + leaderMemberId +\n                            \", logSessionId=\" + logSessionId +\n                            \", isStartup=\" + isStartup);\n                    }\n                }\n                else\n                {","sourceCodeStart":481,"sourceCodeEnd":517,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/Election.java#L481-L517","documentation":"In onNewLeadershipTerm, a follower received a new leadership term whose termBaseLogPosition is greater than the follower's own appendPosition while nextLeadershipTermId does not follow from the follower's known log — i.e. the leader's log position/term bookkeeping is inconsistent with the follower's log, so the election aborts with full state dumped for diagnosis.","triggerScenarios":"A follower's appendPosition (local recorded log position) is behind the leader's termBaseLogPosition and the incoming nextLeadershipTermId/logLeadershipTermId do not line up — e.g. the follower's log recording was trimmed/deleted, or its mark file/snapshot came from a different log history.","commonSituations":"Restoring a snapshot but keeping a mismatched (older/newer) mark file or archive; purged/truncated archive segments the leader assumes exist; joining a cluster whose log starts at positions the member never recorded.","solutions":["Restore the member's mark file, snapshot, and archive recordings together from a single consistent backup","Let the member rejoin as a fresh member (clean cluster dir) and catch up via snapshot","Verify archive recordings were not trimmed past the term base positions while the member was down","Upgrade Aeron if on an old version; some election position edge cases were fixed"],"exampleFix":"// before: mark file from backup A, archive recordings from backup B\nClusterException: invalid newLeadershipTerm - this.appendPosition=... < termBaseLogPosition=...\n// after: restore the complete consistent set (mark file + snapshot + recordings) from one backup, then restart the member","handlingStrategy":"validation","validationCode":"// Before rejoining, verify the member's archive recordings cover the leader's term base positions\n// compare mark file log positions and archive recording start positions with the leader's before starting","typeGuard":null,"tryCatchPattern":"try {\n    clusterMember.start();\n} catch (ClusterException e) {\n    if (e.getMessage().startsWith(\"invalid newLeadershipTerm\")) {\n        // wipe member state and rejoin fresh via snapshot\n        cleanJoin();\n    } else { throw e; }\n}","preventionTips":["Never trim archive recordings below the current term base position while members are catching up","Restore mark file + archive + snapshot from one backup","For a diverged member, prefer a clean rejoin over patching state"],"tags":["aeron","cluster","election","log-position"],"backgroundTag":"internal-invariant-violation","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}