What causes "Prefix length must be /96" in cilium/cilium?

Set --ipv6-nat46x64-cidr to a dedicated /96, e.g. 64:ff9b::/96 (RFC 6052 well-known prefix)

Prefix length must be /96

Error message

Prefix length must be /96

What it means

validateIPv6NAT46x64CIDR parses IPv6NAT46x64CIDR (the NAT46x64 translation prefix) and requires it to be exactly /96, per RFC 6052 which reserves /96 for embedding IPv4 addresses in IPv6. Any other prefix length is rejected.

Source

Thrown at pkg/option/config.go:2160

		return err
	}

	if ones, _ := cidr.Mask.Size(); ones != 64 {
		return fmt.Errorf("Prefix length must be /64")
	}

	c.IPv6ClusterAllocCIDRBase = ip.Mask(cidr.Mask).String()

	return nil
}

func (c *DaemonConfig) validateIPv6NAT46x64CIDR() error {
	parsedPrefix, err := netip.ParsePrefix(c.IPv6NAT46x64CIDR)
	if err != nil {
		return err
	}
	if parsedPrefix.Bits() != 96 {
		return fmt.Errorf("Prefix length must be /96")
	}

	c.IPv6NAT46x64CIDRBase = parsedPrefix.Masked().Addr()
	return nil
}

func (c *DaemonConfig) validateContainerIPLocalReservedPorts() error {
	if c.ContainerIPLocalReservedPorts == "" || c.ContainerIPLocalReservedPorts == defaults.ContainerIPLocalReservedPortsAuto {
		return nil
	}

	if regexp.MustCompile(`^(\d+(-\d+)?)(,\d+(-\d+)?)*$`).MatchString(c.ContainerIPLocalReservedPorts) {
		return nil
	}

	return fmt.Errorf("Invalid comma separated list of ranges for %s option", ContainerIPLocalReservedPorts)
}

View on GitHub (pinned to ac7b90affa)

Solutions

Set --ipv6-nat46x64-cidr to a dedicated /96, e.g. 64:ff9b::/96 (RFC 6052 well-known prefix)
Choose any unused /96 inside your IPv6 ULA/GUA space and ensure it does not collide with pod/node prefixes
Update the cilium-config ConfigMap/Helm value ipv6 Nat46x64CIDR and restart the agent

Example fix

// before
ipv6-nat46x64-cidr: "fd00:dead:beef::/64"
// after
ipv6-nat46x64-cidr: "64:ff9b::/96"

Defensive patterns

Strategy: validation

Validate before calling

func checkNAT46x64CIDR(s string) error {
    p, err := netip.ParsePrefix(s)
    if err != nil {
        return fmt.Errorf("invalid prefix %q: %w", s, err)
    }
    if p.Bits() != 96 {
        return fmt.Errorf("%q must be /96 (RFC 6052), got /%d", s, p.Bits())
    }
    return nil
}

Try / catch

if err := daemonConfig.Validate(vp); err != nil {
    if strings.Contains(err.Error(), "Prefix length must be /96") {
        log.Fatalf("ipv6-nat46x64-cidr must be /96 per RFC 6052: %v", err)
    }
    return err
}

Prevention

Use 64:ff9b::/96 (the RFC 6052 well-known prefix) unless you have a reason not to
Never reuse an existing /64 subnet as the NAT46x64 prefix
Remember: the option is validated only when NAT46x64 features are configured — set it explicitly
Check the rendered Helm value with helm template before applying

When it happens

Trigger: Calling DaemonConfig.Validate() (via validateIPv6NAT46x64CIDR) when --ipv6-nat46x64-cidr is a valid IPv6 prefix but its Bits() != 96 — e.g. /64 or /128.

Common situations: Reusing an existing /64 subnet as the NAT46x64 prefix; omitting configuration so a defaulted/wrong prefix is validated; hand-editing values in the cilium-config ConfigMap without knowing the RFC 6052 /96 requirement.

Related errors

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