{"record":{"id":"b2020e3f03428a7f","repo":"hashicorp/nomad","slug":"unsupported-minimum-common-raft-protocol-version","errorCode":null,"errorMessage":"unsupported minimum common raft protocol version","messagePattern":"unsupported minimum common raft protocol version","errorType":"http","errorClass":null,"httpStatus":400,"severity":"error","filePath":"nomad/operator_endpoint.go","lineNumber":242,"sourceCode":"\t// currently no leader.\n\tif reply.From.Address == \"\" || reply.From.ID == \"\" {\n\t\treply.Err = structs.ErrNoLeader\n\t\treturn structs.NewErrRPCCoded(http.StatusServiceUnavailable, structs.ErrNoLeader.Error())\n\t}\n\n\t// while this is a somewhat more expensive test than later ones, if this\n\t// test fails, they will _never_ be able to do a transfer. We do this after\n\t// ACL checks though, so as to not leak cluster info to non-validated users.\n\tminRaftProtocol, err := op.srv.MinRaftProtocol()\n\tif err != nil {\n\t\treply.Err = err\n\t\treturn structs.NewErrRPCCoded(http.StatusInternalServerError, err.Error())\n\t}\n\n\t// TransferLeadership is not supported until Raft protocol v3 or greater.\n\tif minRaftProtocol < 3 {\n\t\top.logger.Warn(\"unsupported minimum common raft protocol version\", \"required\", \"3\", \"current\", minRaftProtocol)\n\t\treply.Err = errors.New(\"unsupported minimum common raft protocol version\")\n\t\treturn structs.NewErrRPCCoded(http.StatusBadRequest, reply.Err.Error())\n\t}\n\n\tvar kind, testedVal string\n\n\t// The request must provide either an ID or an Address, this lets us validate\n\t// the request\n\treq.Validate()\n\tswitch {\n\tcase req.ID != \"\":\n\t\tkind, testedVal = \"id\", string(req.ID)\n\tcase req.Address != \"\":\n\t\tkind, testedVal = \"address\", string(req.Address)\n\tdefault:\n\t\treply.Err = errors.New(\"must provide peer id or address\")\n\t\treturn structs.NewErrRPCCoded(http.StatusBadRequest, reply.Err.Error())\n\t}\n","sourceCodeStart":224,"sourceCodeEnd":260,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/operator_endpoint.go#L224-L260","documentation":"TransferLeadershipToPeer (operator raft transfer-leadership RPC) refuses to run when the cluster-wide minimum common Raft protocol version is below 3, since Raft protocol v3 is required for explicit leadership transfer. The server returns a 400 with this message after logging a warning with required vs current versions.","triggerScenarios":"Running `nomad operator raft transfer-leadership -peer-id <id>` (or the equivalent HTTP POST to /v1/operator/raft/transfer-leadership) while any server in the cluster still speaks Raft protocol v2 or lower (Nomad < 0.8 servers present, or min_raft_protocol/raft_protocol lowered below 3 on a peer).","commonSituations":"Mixed-version clusters during rolling upgrades; operators manually setting raft_protocol = 2 in server config for legacy compatibility; newly added old-version servers dragging down min common protocol.","solutions":["Upgrade all Nomad servers to a version using Raft protocol 3+ and remove any raft_protocol < 3 settings in server blocks","Check `nomad operator raft list-peers` (or the agent members output) to find the peer still on an older protocol and upgrade/restart it","As a workaround, let Raft transfer leadership naturally (stop the leader) instead of using explicit transfer"],"exampleFix":"// before\nserver {\n  raft_protocol = 2\n}\n// after\nserver {\n  raft_protocol = 3\n}","handlingStrategy":"validation","validationCode":"peers, _, _ := client.Operator().RaftPeers(nil)\nfor _, p := range peers {\n    if p.RaftProtocol < 3 {\n        return fmt.Errorf(\"peer %s on raft protocol %d; upgrade before transfer\", p.ID, p.RaftProtocol)\n    }\n}","typeGuard":null,"tryCatchPattern":"resp, err := client.Operator().RaftTransferLeadership(peerID, addr, nil)\nif err != nil && strings.Contains(err.Error(), \"unsupported minimum common raft protocol\") {\n    // upgrade the lagging server, then retry\n}","preventionTips":["Keep all servers on Nomad versions using raft protocol 3+","Never lower raft_protocol below 3 in server configs","Check min common raft protocol after every server join/upgrade"],"tags":["nomad","raft","consensus","versioning","leader-election"],"backgroundTag":"raft-protocol-version-unsupported","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"}