specified NAT table size %d must be greater or equal to %d

Q: What causes "specified NAT table size %d must be greater or equal to %d" in cilium/cilium?

Set --bpf-nat-global-max to at least 1024 (LimitTableMin)

Error message

specified NAT table size %d must be greater or equal to %d

What it means

DaemonConfig validation rejects a NAT map size (--bpf-nat-global-max) below LimitTableMin (1<<10 = 1024 entries). Cilium requires the global NAT table to hold at least 1024 entries; smaller values are treated as invalid configuration and abort agent startup.

Source

Thrown at pkg/option/config.go:2929

func (c *DaemonConfig) checkMapSizeLimits() error {
	if c.AuthMapEntries < AuthMapEntriesMin {
		return fmt.Errorf("specified AuthMap max entries %d must be greater or equal to %d", c.AuthMapEntries, AuthMapEntriesMin)
	}
	if c.AuthMapEntries > AuthMapEntriesMax {
		return fmt.Errorf("specified AuthMap max entries %d must not exceed maximum %d", c.AuthMapEntries, AuthMapEntriesMax)
	}

	if c.CTMapEntriesGlobalTCP < LimitTableMin || c.CTMapEntriesGlobalAny < LimitTableMin {
		return fmt.Errorf("specified CT tables values %d/%d must be greater or equal to %d",
			c.CTMapEntriesGlobalTCP, c.CTMapEntriesGlobalAny, LimitTableMin)
	}
	if c.CTMapEntriesGlobalTCP > LimitTableMax || c.CTMapEntriesGlobalAny > LimitTableMax {
		return fmt.Errorf("specified CT tables values %d/%d must not exceed maximum %d",
			c.CTMapEntriesGlobalTCP, c.CTMapEntriesGlobalAny, LimitTableMax)
	}

	if c.NATMapEntriesGlobal < LimitTableMin {
		return fmt.Errorf("specified NAT table size %d must be greater or equal to %d",
			c.NATMapEntriesGlobal, LimitTableMin)
	}
	if c.NATMapEntriesGlobal > LimitTableMax {
		return fmt.Errorf("specified NAT tables size %d must not exceed maximum %d",
			c.NATMapEntriesGlobal, LimitTableMax)
	}
	if c.NATMapEntriesGlobal > c.CTMapEntriesGlobalTCP+c.CTMapEntriesGlobalAny {
		if c.NATMapEntriesGlobal == NATMapEntriesGlobalDefault {
			// Auto-size for the case where CT table size was adapted but NAT still on default
			c.NATMapEntriesGlobal = int((c.CTMapEntriesGlobalTCP + c.CTMapEntriesGlobalAny) * 2 / 3)
		} else {
			return fmt.Errorf("specified NAT tables size %d must not exceed maximum CT table size %d",
				c.NATMapEntriesGlobal, c.CTMapEntriesGlobalTCP+c.CTMapEntriesGlobalAny)
		}
	}

	if c.FragmentsMapEntries < FragmentsMapMin {
		return fmt.Errorf("specified max entries %d for fragment-tracking map must be greater or equal to %d",

View on GitHub (pinned to ac7b90affa)

Solutions

Set --bpf-nat-global-max to at least 1024 (LimitTableMin)
Remove the flag entirely to use the default NATMapEntriesGlobalDefault (2/3 of combined CT defaults, auto-sized)
Fix any calculating script so the value cannot drop below 1024
Also keep NAT size <= LimitTableMax and <= CT TCP+Any total to avoid the companion maximum/NAT-vs-CT errors

Example fix

# before
--bpf-nat-global-max=512
# after
--bpf-nat-global-max=1024

Defensive patterns

Strategy: validation

Validate before calling

const LimitTableMin = 1 << 10
function validateNATMin(nat) {
  if (!Number.isInteger(nat)) throw new TypeError('NAT entries must be an integer');
  if (nat < LimitTableMin) throw new RangeError(`NAT table size ${nat} must be >= ${LimitTableMin}`);
  return true;
}

Type guard

function hasValidNATMin(c) { return Number.isInteger(c.NATMapEntriesGlobal) && c.NATMapEntriesGlobal >= 1024; }

Prevention

Never set --bpf-nat-global-max below 1024; omit the flag to use defaults
Ensure sizing formulas have a Math.max(value, 1024) floor
Do not reuse policy-map minimums (256) for NAT sizing
Validate generated agent flags in CI before rollout

When it happens

Trigger: option.Config.Validate() runs with DaemonConfig.NATMapEntriesGlobal < 1024, e.g. --bpf-nat-global-max=512 or a computed value that rounded/underflowed to a tiny number.

Common situations: Hand-tuned small clusters set NAT entries too low; a script divides total memory by a large constant; someone confuses this limit with per-CPU or policy map minimums (PolicyMapMin=256).

Related errors

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