What causes "nat-stats config: %q must be between [%d, %d]" in cilium/cilium?

Set nat-map-stats-entries to a value between 1 and 4096 inclusive

nat-stats config: %q must be between [%d, %d]

Error message

nat-stats config: %q must be between [%d, %d]

What it means

The NAT statistics cell validates nat-map-stats-entries in newStats: if NatMapStatKStoredEntries is not in [1, 4096] (min..maxNatMapStatKStoredEntries), startup of the stats cell fails with this error. Interval of 0 disables the feature and skips validation.

Source

Thrown at pkg/maps/nat/stats/stats.go:136

	NatMap4   nat.NatMap4
	NatMap6   nat.NatMap6
	Jobs      job.Group
	Metrics   natMetrics
	Config    Config
	LBConfig  loadbalancer.Config
	Health    cell.Health
}

const nodePortMaxNAT = 65535

func newStats(params params) (*Stats, error) {
	if params.Config.NATMapStatInterval == 0 {
		return nil, nil
	}

	if params.Config.NatMapStatKStoredEntries > maxNatMapStatKStoredEntries ||
		params.Config.NatMapStatKStoredEntries < minNatMapStatKStoredEntries {
		return nil, fmt.Errorf("nat-stats config: %q must be between [%d, %d]",
			natMapStatsEntriesName, minNatMapStatKStoredEntries, maxNatMapStatKStoredEntries)
	}

	// number of available source-ports is ephemeral range subtracting those
	// used by node-ports.
	maxAvailPorts := nodePortMaxNAT - (params.LBConfig.NodePortMax + 1)
	m := &Stats{
		logger:   params.Logger,
		metrics:  params.Metrics,
		config:   params.Config,
		maxPorts: int(maxAvailPorts),
		db:       params.DB,
		table:    params.Table,
	}

	m.observable4, m.next4, m.complete4 =
		stream.Multicast[TupleCountIterator]()
	m.observable6, m.next6, m.complete6 =

View on GitHub (pinned to ac7b90affa)

Solutions

Set nat-map-stats-entries to a value between 1 and 4096 inclusive
If you need more than 4096, keep 4096 (the supported maximum) or disable the feature with nat-map-stats-interval=0
Verify both options together: entries validation only runs when the interval is non-zero

Example fix

// before
nat-map-stats-interval=30s
nat-map-stats-entries=8192
// error: "nat-map-stats-entries" must be between [1, 4096]
// after
nat-map-stats-interval=30s
nat-map-stats-entries=4096

Defensive patterns

Strategy: validation

Validate before calling

const minNatMapStatKStoredEntries, maxNatMapStatKStoredEntries = 1, 4096
if natStatsInterval != 0 && (natMapStatEntries > maxNatMapStatKStoredEntries || natMapStatEntries < minNatMapStatKStoredEntries) {
    return fmt.Errorf("nat-map-stats-entries must be in [%d, %d]", minNatMapStatKStoredEntries, maxNatMapStatKStoredEntries)
}

Type guard

null

Try / catch

if err := startNatStatsCell(params); err != nil && strings.Contains(err.Error(), "nat-stats config") {
    log.Error("invalid nat-map-stats-entries; must be 1..4096 (or disable via interval=0)", "err", err)
}

Prevention

Keep nat-map-stats-entries within 1..4096
Remember validation only runs when nat-map-stats-interval is non-zero; set interval=0 to disable the feature
Clamp the configured value before passing it to the agent
Read the option as an entry count, not a size

When it happens

Trigger: Setting nat-map-stats-entries to 0 or a negative number, or to anything above 4096, while nat-map-stats-interval is non-zero (feature enabled).

Common situations: Operators raising the stored-entries value for busy clusters and overshooting the 4096 cap; copy-pasted config with 0 entries while an interval is configured; misreading the option as a byte/KB size.

Related errors

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/99badd0ea6f81dd1. Report an issue: GitHub.