cilium/cilium · critical

unable to initialize IPv6 allocator: %w

Error message

unable to initialize IPv6 allocator: %w

What it means

In AllocatorOperator.Init, an error returned by cidralloc.NewCIDRSets(true, ClusterPoolIPv6CIDR, ClusterPoolIPv6MaskSize) is wrapped as 'unable to initialize IPv6 allocator'. It indicates the configured IPv6 CIDR list or mask size could not be parsed or is invalid, preventing IPv6 pool allocation setup.

Source

Thrown at operator/pkg/ipam/allocator/clusterpool/clusterpool.go:68

		}

		v4Allocators, err := cidralloc.NewCIDRSets(false, a.ClusterPoolIPv4CIDR, a.ClusterPoolIPv4MaskSize)
		if err != nil {
			return fmt.Errorf("unable to initialize IPv4 allocator: %w", err)
		}
		a.v4CIDRSet = v4Allocators
	} else if len(a.ClusterPoolIPv4CIDR) != 0 {
		return fmt.Errorf("cluster-pool-ipv4-cidr must not be set if IPv4 is disabled")
	}

	if option.Config.EnableIPv6 {
		if len(a.ClusterPoolIPv6CIDR) == 0 {
			return fmt.Errorf("cluster-pool-ipv6-cidr must be provided when using ClusterPool")
		}

		v6Allocators, err := cidralloc.NewCIDRSets(true, a.ClusterPoolIPv6CIDR, a.ClusterPoolIPv6MaskSize)
		if err != nil {
			return fmt.Errorf("unable to initialize IPv6 allocator: %w", err)
		}
		a.v6CIDRSet = v6Allocators
	} else if len(a.ClusterPoolIPv6CIDR) != 0 {
		return fmt.Errorf("cluster-pool-ipv6-cidr must not be set if IPv6 is disabled")
	}

	return nil
}

// Start kicks off Operator allocation.
func (a *AllocatorOperator) Start(ctx context.Context, updater allocator.CiliumNodeGetterUpdater, iMetrics trigger.MetricsObserver) (allocator.NodeEventHandler, error) {
	a.logger.Info(
		"Starting ClusterPool IP allocator",
		logfields.IPv4CIDRs, a.ClusterPoolIPv4CIDR,
		logfields.IPv6CIDRs, a.ClusterPoolIPv6CIDR,
	)

	nodeManager := podcidr.NewNodesPodCIDRManager(a.logger, a.v4CIDRSet, a.v6CIDRSet, updater, iMetrics)

View on GitHub (pinned to ac7b90affa)

Solutions

1. Read the wrapped cause in the operator log to identify the offending CIDR
2. Fix the --cluster-pool-ipv6-cidr entries to valid IPv6 CIDRs (e.g. 2001:db8::/56)
3. Set a valid --cluster-pool-ipv6-mask-size (commonly 116) consistent with the prefix

Example fix

// before
--cluster-pool-ipv6-cidr=2001:db8::
// after
--cluster-pool-ipv6-cidr=2001:db8::/56

for _, c := range strings.Split(cfg.ClusterPoolIPv6CIDR, ",") {
    ip := net.ParseIP(strings.TrimSpace(c))
    if ip == nil || ip.To4() != nil || !strings.Contains(c, "/") {
        return fmt.Errorf("invalid IPv6 CIDR %q", c)
    }
}
if cfg.ClusterPoolIPv6MaskSize <= 0 || cfg.ClusterPoolIPv6MaskSize > 128 {
    return fmt.Errorf("invalid cluster-pool-ipv6-mask-size %d", cfg.ClusterPoolIPv6MaskSize)
}

if err := alloc.Init(ctx, logger); err != nil {
    if strings.Contains(err.Error(), "unable to initialize IPv6 allocator") {
        logger.Error("bad IPv6 CIDR/mask config; check --cluster-pool-ipv6-cidr and --cluster-pool-ipv6-mask-size", "err", err)
    }
    return err
}

When it happens

Trigger: Init passes an invalid ClusterPoolIPv6CIDR (bad CIDR syntax) or invalid ClusterPoolIPv6MaskSize to cidralloc.NewCIDRSets with isV6=true, and the returned error is wrapped.

Common situations: Malformed IPv6 prefix (missing /prefixlen, wrong address); mask size larger than prefix allows or beyond 128 bits; Helm templating producing empty or double-comma list entries.

Related errors

• not ready
• no cilium agent pods found
• invalid cidr family: %s
• cannot change IPv6 mask size in existing pool %q
• unable to detect minimum Cilium version

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