{"record":{"id":"24961791c6115f20","repo":"hashicorp/nomad","slug":"raft-protocol-must-be-3-in-nomad-v1-4-and-later-g","errorCode":null,"errorMessage":"raft_protocol must be 3 in Nomad v1.4 and later, got %d","messagePattern":"raft_protocol must be 3 in Nomad v1\\.4 and later, got (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/agent.go","lineNumber":241,"sourceCode":"\t\tconf.Datacenter = agentConfig.Datacenter\n\t}\n\tif agentConfig.NodeName != \"\" {\n\t\tconf.NodeName = agentConfig.NodeName\n\t}\n\tif agentConfig.Server.BootstrapExpect > 0 {\n\t\tconf.BootstrapExpect = agentConfig.Server.BootstrapExpect\n\t}\n\tif agentConfig.DataDir != \"\" {\n\t\tconf.DataDir = filepath.Join(agentConfig.DataDir, \"server\")\n\t}\n\tif agentConfig.Server.DataDir != \"\" {\n\t\tconf.DataDir = agentConfig.Server.DataDir\n\t}\n\tif agentConfig.Server.RaftProtocol != 0 {\n\t\tconf.RaftConfig.ProtocolVersion = raft.ProtocolVersion(agentConfig.Server.RaftProtocol)\n\t}\n\tif v := conf.RaftConfig.ProtocolVersion; v != 3 {\n\t\treturn nil, fmt.Errorf(\"raft_protocol must be 3 in Nomad v1.4 and later, got %d\", v)\n\t}\n\traftMultiplier := int(DefaultRaftMultiplier)\n\tif agentConfig.Server.RaftMultiplier != nil && *agentConfig.Server.RaftMultiplier != 0 {\n\t\traftMultiplier = *agentConfig.Server.RaftMultiplier\n\t\tif raftMultiplier < 1 || raftMultiplier > MaxRaftMultiplier {\n\t\t\treturn nil, fmt.Errorf(\"raft_multiplier cannot be %d. Must be between 1 and %d\", *agentConfig.Server.RaftMultiplier, MaxRaftMultiplier)\n\t\t}\n\t}\n\n\tif vPtr := agentConfig.Server.RaftTrailingLogs; vPtr != nil {\n\t\tif *vPtr < 1 {\n\t\t\treturn nil, fmt.Errorf(\"raft_trailing_logs must be non-negative, got %d\", *vPtr)\n\t\t}\n\t\tconf.RaftConfig.TrailingLogs = uint64(*vPtr)\n\t}\n\n\tif vPtr := agentConfig.Server.RaftSnapshotInterval; vPtr != nil {\n\t\tdur, err := time.ParseDuration(*vPtr)","sourceCodeStart":223,"sourceCodeEnd":259,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/agent.go#L223-L259","documentation":"Nomad v1.4 removed support for Raft protocol versions other than 3. convertServerConfig rejects any configured raft_protocol that resolves to a ProtocolVersion other than 3 (including 0 defaulting via explicit values) to prevent incompatible cluster state.","triggerScenarios":"Setting server { raft_protocol = 1 } (or 2, or any value != 3) in the agent config, then starting or reloading the agent (serverConfig/handleReload call convertServerConfig).","commonSituations":"Upgrading a pre-1.4 cluster config that still carries raft_protocol = 0/1 settings; copying old example configs; stale config management templates pinned to old defaults.","solutions":["Remove the raft_protocol stanza entirely from server config (v1.4+ always uses 3).","Or set raft_protocol = 3 explicitly.","If a reload triggered it, correct the config and re-issue the reload (SIGHUP)."],"exampleFix":"// before\nserver {\n  raft_protocol = 1\n}\n// after\nserver {\n  raft_protocol = 3\n}","handlingStrategy":"validation","validationCode":"# shell pre-check of config before start\nif grep -E 'raft_protocol' nomad.hcl | grep -vE 'raft_protocol\\s*=\\s*3'; then\n  echo \"raft_protocol must be 3 for Nomad >= 1.4\"; exit 1\nfi","typeGuard":null,"tryCatchPattern":"conf, err := convertServerConfig(agentCfg)\nif err != nil {\n    if strings.Contains(err.Error(), \"raft_protocol must be 3\") {\n        return fmt.Errorf(\"remove raft_protocol from server config for Nomad >= 1.4: %w\", err)\n    }\n    return err\n}","preventionTips":["Delete raft_protocol from all server configs when upgrading past Nomad 1.4.","Grep config repos for 'raft_protocol' during version upgrades.","Pin config templates to the target Nomad version."],"tags":["nomad","raft","config","upgrade"],"backgroundTag":"unsupported-config-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"}