hashicorp/nomad · error

raft_snapshot_threshold must be non-negative, got %d

Error message

raft_snapshot_threshold must be non-negative, got %d

What it means

In convertServerConfig, raft_snapshot_threshold was set to a value < 1; Raft requires a positive snapshot threshold, so agent config conversion fails and the server refuses to start with the invalid setting.

Source

Thrown at command/agent/agent.go:271

			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)
		}
		conf.RaftConfig.SnapshotInterval = dur
	}

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

	conf.RaftConfig.ElectionTimeout *= time.Duration(raftMultiplier)
	conf.RaftConfig.HeartbeatTimeout *= time.Duration(raftMultiplier)
	conf.RaftConfig.LeaderLeaseTimeout *= time.Duration(raftMultiplier)
	conf.RaftConfig.CommitTimeout *= time.Duration(raftMultiplier)

	if agentConfig.Server.NumSchedulers != nil {
		conf.NumSchedulers = *agentConfig.Server.NumSchedulers
	}
	if len(agentConfig.Server.EnabledSchedulers) != 0 {
		// Convert to a set and require the core scheduler
		set := make(map[string]struct{}, 4)
		set[structs.JobTypeCore] = struct{}{}
		for _, sched := range agentConfig.Server.EnabledSchedulers {
			set[sched] = struct{}{}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set raft_snapshot_threshold to a positive integer (default 8192).
2. Remove the stanza to use the Raft library default.
3. If snapshot frequency is a concern, adjust raft_snapshot_interval instead.

Example fix

// before
server {
  raft_snapshot_threshold = 0
}
// after
server {
  raft_snapshot_threshold = 8192
}

// Go: pre-validate
if v := cfg.Server.RaftSnapshotThreshold; v != nil && *v < 1 {
    return fmt.Errorf("raft_snapshot_threshold must be >= 1")
}

conf, err := convertServerConfig(agentCfg)
if err != nil {
    if strings.Contains(err.Error(), "raft_snapshot_threshold") {
        return fmt.Errorf("set raft_snapshot_threshold to a positive integer (default 8192): %w", err)
    }
    return err
}

When it happens

Trigger: Setting server { raft_snapshot_threshold = 0 } (or negative) during agent start or runtime reload.

Common situations: Trying to 'disable' snapshotting with 0; config templating emitting 0 for missing values; copying configs from other HashiCorp tools with different validation.

Related errors

• raft_protocol must be 3 in Nomad v1.4 and later, got %d
• 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
• plugin not found

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