{"record":{"id":"20696677ee47f3a1","repo":"hashicorp/nomad","slug":"leadership-transfer-not-supported-with-raft-versio","errorCode":null,"errorMessage":"leadership transfer not supported with Raft version lower than 3","messagePattern":"leadership transfer not supported with Raft version lower than 3","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/leader.go","lineNumber":208,"sourceCode":"\t\t}\n\n\t\t// \"cannot transfer leadership to itself\"\n\t\t// Handled at top of function, but reapplied here to prevent retrying if\n\t\t// it occurs while we are retrying\n\t\tif err.Error() == \"cannot transfer leadership to itself\" {\n\t\t\ts.logger.Debug(\"leadership transfer to current leader is a no-op\")\n\t\t\treturn nil\n\t\t}\n\n\t\t// ErrRaftShutdown: Don't retry if raft is shut down.\n\t\tif err == raft.ErrRaftShutdown {\n\t\t\treturn err\n\t\t}\n\n\t\t// ErrUnsupportedProtocol: Don't retry if the Raft version doesn't\n\t\t// support leadership transfer since this will never succeed.\n\t\tif err == raft.ErrUnsupportedProtocol {\n\t\t\treturn fmt.Errorf(\"leadership transfer not supported with Raft version lower than 3\")\n\t\t}\n\n\t\t// ErrEnqueueTimeout: This seems to be the valid time to retry.\n\t\ts.logger.Error(\"failed to transfer leadership attempt, will retry\",\n\t\t\t\"attempt\", i,\n\t\t\t\"retry_limit\", retryCount,\n\t\t\t\"error\", err,\n\t\t)\n\t\tlastError = err\n\t}\n\treturn fmt.Errorf(\"failed to transfer leadership in %d attempts. last error: %w\", retryCount, lastError)\n}\n\nfunc (s *Server) leadershipTransfer() error {\n\tretryCount := 3\n\tfor i := range retryCount {\n\t\terr := s.raft.LeadershipTransfer().Error()\n\t\tif err == nil {","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/leader.go#L190-L226","documentation":"When transferring leadership to a specific peer, Nomad retries raft.LeadershipTransferToServer; raft.ErrUnsupportedProtocol means the target cluster's Raft protocol version is below 3, which does not support leadership transfer at all. Nomad converts this into a non-retried terminal error.","triggerScenarios":"TransferLeadershipToPeer invoked (e.g. `nomad server force-leave`-driven step-down, operator-triggered transfer, or leaderLoop fallback) against a Raft setup where raft protocol version < 3 (config `raft_protocol` set to 1 or 2).","commonSituations":"Clusters upgraded from very old Nomad versions still running raft_protocol = 2; mixed-version clusters where a server was configured with a lower Raft protocol; operators forcing leadership handoff during maintenance on legacy nodes.","solutions":["Raise the server's raft_protocol config to 3 (or higher) on all servers and restart the agents.","Restart Nomad servers one at a time to roll the Raft protocol version across the cluster.","If upgrade isn't possible, trigger a normal leader step-down (restart the leader) instead of an explicit transfer."],"exampleFix":"// before (agent config)\nserver { raft_protocol = 2 }\n// after\nserver { raft_protocol = 3 }","handlingStrategy":"validation","validationCode":"if cfg.Server.RaftProtocol < 3 {\n    return fmt.Errorf(\"leadership transfer requires raft_protocol >= 3 (current: %d)\", cfg.Server.RaftProtocol)\n}","typeGuard":null,"tryCatchPattern":"if err := transferLeadership(peer); err != nil {\n    if strings.Contains(err.Error(), \"not supported with Raft version lower than 3\") {\n        return fmt.Errorf(\"upgrade raft_protocol on all servers before transferring leadership\")\n    }\n    return err\n}","preventionTips":["Run raft_protocol 3+ on every Nomad server.","Check Raft protocol version via `nomad operator raft list-peers` before maintenance transfers.","During version upgrades, roll servers so protocol versions are uniform.","Fall back to leader restart for step-down on legacy clusters."],"tags":["nomad","raft","leadership","version-compatibility"],"backgroundTag":"unsupported-protocol-version","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}