hashicorp/nomad · error

raft_multiplier cannot be %d. Must be between 1 and %d

Error message

raft_multiplier cannot be %d. Must be between 1 and %d

What it means

The raft_multiplier scales Raft election/heartbeat timeouts. Nomad validates it against DefaultRaftMultiplier and MaxRaftMultiplier bounds in convertServerConfig; values outside [1, MaxRaftMultiplier] are rejected.

Source

Thrown at command/agent/agent.go:247

		conf.BootstrapExpect = agentConfig.Server.BootstrapExpect
	}
	if agentConfig.DataDir != "" {
		conf.DataDir = filepath.Join(agentConfig.DataDir, "server")
	}
	if agentConfig.Server.DataDir != "" {
		conf.DataDir = agentConfig.Server.DataDir
	}
	if agentConfig.Server.RaftProtocol != 0 {
		conf.RaftConfig.ProtocolVersion = raft.ProtocolVersion(agentConfig.Server.RaftProtocol)
	}
	if v := conf.RaftConfig.ProtocolVersion; v != 3 {
		return nil, fmt.Errorf("raft_protocol must be 3 in Nomad v1.4 and later, got %d", v)
	}
	raftMultiplier := int(DefaultRaftMultiplier)
	if agentConfig.Server.RaftMultiplier != nil && *agentConfig.Server.RaftMultiplier != 0 {
		raftMultiplier = *agentConfig.Server.RaftMultiplier
		if raftMultiplier < 1 || raftMultiplier > MaxRaftMultiplier {
			return nil, fmt.Errorf("raft_multiplier cannot be %d. Must be between 1 and %d", *agentConfig.Server.RaftMultiplier, MaxRaftMultiplier)
		}
	}

	if vPtr := agentConfig.Server.RaftTrailingLogs; vPtr != nil {
		if *vPtr < 1 {
			return nil, fmt.Errorf("raft_trailing_logs must be non-negative, got %d", *vPtr)
		}
		conf.RaftConfig.TrailingLogs = uint64(*vPtr)
	}

	if vPtr := agentConfig.Server.RaftSnapshotInterval; vPtr != nil {
		dur, err := time.ParseDuration(*vPtr)
		if err != nil {
			return nil, err
		}
		if dur < 5*time.Millisecond {
			return nil, fmt.Errorf("raft_snapshot_interval must be greater than 5ms, got %q", *vPtr)
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set raft_multiplier within the allowed range (>=1 and <= MaxRaftMultiplier; Nomad's default is 5, max is typically 30).
2. Remove the stanza to use DefaultRaftMultiplier.
3. For slow networks, tune heartbeat_grace or underlying network instead of exceeding the multiplier cap.

Example fix

// before
server {
  raft_multiplier = 100
}
// after
server {
  raft_multiplier = 30
}

// Go: validate before building agent config
if m := cfg.Server.RaftMultiplier; m != nil && (*m < 1 || *m > maxRaftMultiplier) {
    return fmt.Errorf("raft_multiplier %d out of range [1,%d]", *m, maxRaftMultiplier)
}

conf, err := convertServerConfig(agentCfg)
if err != nil {
    if strings.Contains(err.Error(), "raft_multiplier cannot be") {
        return fmt.Errorf("fix raft_multiplier range (1..%d): %w", maxRaftMultiplier, err)
    }
    return err
}

When it happens

Trigger: Setting server { raft_multiplier = N } where N < 1 or N > MaxRaftMultiplier during agent start (serverConfig) or runtime reload (handleReload).

Common situations: 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.

Related errors

• raft_protocol must be 3 in Nomad v1.4 and later, got %d
• raft_trailing_logs must be non-negative, got %d
• raft_snapshot_interval must be greater than 5ms, got %q
• raft_snapshot_threshold must be non-negative, got %d
• plugin not found

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/3440436b1c2eab10. Report an issue: GitHub.