{"record":{"id":"3440436b1c2eab10","repo":"hashicorp/nomad","slug":"raft-multiplier-cannot-be-d-must-be-between-1-an","errorCode":null,"errorMessage":"raft_multiplier cannot be %d. Must be between 1 and %d","messagePattern":"raft_multiplier cannot be (.+?)\\. Must be between 1 and (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/agent/agent.go","lineNumber":247,"sourceCode":"\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)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tif dur < 5*time.Millisecond {\n\t\t\treturn nil, fmt.Errorf(\"raft_snapshot_interval must be greater than 5ms, got %q\", *vPtr)\n\t\t}","sourceCodeStart":229,"sourceCodeEnd":265,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/agent/agent.go#L229-L265","documentation":"The raft_multiplier scales Raft election/heartbeat timeouts. Nomad validates it against DefaultRaftMultiplier and MaxRaftMultiplier bounds in convertServerConfig; values outside [1, MaxRaftMultiplier] are rejected.","triggerScenarios":"Setting server { raft_multiplier = N } where N < 1 or N > MaxRaftMultiplier during agent start (serverConfig) or runtime reload (handleReload).","commonSituations":"Aggressively tuning heartbeat timeouts for lossy WAN clusters and overshooting the max; typos (e.g. raft_multiplier = 100); copying tuning advice from Consul/other Consul-derived products with different limits.","solutions":["Set raft_multiplier within the allowed range (>=1 and <= MaxRaftMultiplier; Nomad's default is 5, max is typically 30).","Remove the stanza to use DefaultRaftMultiplier.","For slow networks, tune heartbeat_grace or underlying network instead of exceeding the multiplier cap."],"exampleFix":"// before\nserver {\n  raft_multiplier = 100\n}\n// after\nserver {\n  raft_multiplier = 30\n}","handlingStrategy":"validation","validationCode":"// Go: validate before building agent config\nif m := cfg.Server.RaftMultiplier; m != nil && (*m < 1 || *m > maxRaftMultiplier) {\n    return fmt.Errorf(\"raft_multiplier %d out of range [1,%d]\", *m, maxRaftMultiplier)\n}","typeGuard":null,"tryCatchPattern":"conf, err := convertServerConfig(agentCfg)\nif err != nil {\n    if strings.Contains(err.Error(), \"raft_multiplier cannot be\") {\n        return fmt.Errorf(\"fix raft_multiplier range (1..%d): %w\", maxRaftMultiplier, err)\n    }\n    return err\n}","preventionTips":["Keep raft_multiplier between 1 and 30 (default 5).","Only set it for high-latency networks; document the chosen value.","Lint Nomad configs in CI before rollout."],"tags":["nomad","raft","config"],"backgroundTag":"config-value-out-of-range","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"}