hashicorp/nomad · error

raft_protocol must be 3 in Nomad v1.4 and later, got %d

Error message

raft_protocol must be 3 in Nomad v1.4 and later, got %d

What it means

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.

Source

Thrown at command/agent/agent.go:241

		conf.Datacenter = agentConfig.Datacenter
	}
	if agentConfig.NodeName != "" {
		conf.NodeName = agentConfig.NodeName
	}
	if agentConfig.Server.BootstrapExpect > 0 {
		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)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Remove the raft_protocol stanza entirely from server config (v1.4+ always uses 3).
2. Or set raft_protocol = 3 explicitly.
3. If a reload triggered it, correct the config and re-issue the reload (SIGHUP).

Example fix

// before
server {
  raft_protocol = 1
}
// after
server {
  raft_protocol = 3
}

# shell pre-check of config before start
if grep -E 'raft_protocol' nomad.hcl | grep -vE 'raft_protocol\s*=\s*3'; then
  echo "raft_protocol must be 3 for Nomad >= 1.4"; exit 1
fi

conf, err := convertServerConfig(agentCfg)
if err != nil {
    if strings.Contains(err.Error(), "raft_protocol must be 3") {
        return fmt.Errorf("remove raft_protocol from server config for Nomad >= 1.4: %w", err)
    }
    return err
}

When it happens

Trigger: 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).

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

Related errors

• raft_multiplier cannot be %d. Must be between 1 and %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
• existing BoltDB raft store found at %s; run 'nomad operator

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