cilium/cilium · error

the provided network does not match the current range

Error message

the provided network does not match the current range

What it means

ErrMismatchedNetwork is returned by the IPAM allocator's Restore function when the persisted allocation state being restored belongs to a different network range than the range the allocator is currently configured for. The allocator refuses to restore mismatched state to prevent allocating IPs outside the current range.

Source

Thrown at pkg/ipam/service/ipallocator/allocator.go:30

	"github.com/cilium/cilium/pkg/ipam/service/allocator"
)

// Interface manages the allocation of IP addresses out of a range. Interface
// should be threadsafe.
type Interface interface {
	Allocate(netip.Addr) error
	AllocateNext() (netip.Addr, error)
	Release(netip.Addr) error
	ForEach(func(netip.Addr))
	CIDR() netip.Prefix
	Has(addr netip.Addr) bool
}

var (
	ErrFull              = errors.New("range is full")
	ErrAllocated         = errors.New("provided IP is already allocated")
	ErrMismatchedNetwork = errors.New("the provided network does not match the current range")
)

type ErrNotInRange struct {
	ValidRange string
}

func (e *ErrNotInRange) Error() string {
	return fmt.Sprintf("provided IP is not in the valid range. The range of valid IPs is %s", e.ValidRange)
}

// CIDRRangeOption is a functional option for NewCIDRRange.
type CIDRRangeOption func(*cidrRangeOptions)

type cidrRangeOptions struct {
	allowFirstIP bool
	allowLastIP  bool
}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Verify the persisted allocation range matches the node's currently assigned allocation prefix; re-sync the node's CIDR from the control plane
2. Delete the stale allocation state for this node (kvstore key) so it can be re-created with the correct range
3. Revert the CIDR/configuration change so the allocator range matches the persisted state again

Example fix

// before: restoring stale state for old range
alloc.Restore(ctx, oldRange, staleAllocator)
// after: ensure the range passed matches the allocator's current range
currentRange, _ := types.NewPrefixFromNetIPNet(node.AllocatedIPv4CIDR)
alloc.Restore(ctx, currentRange, staleAllocator)

// Ensure persisted range matches before restoring
func canRestore(alloc *Allocator, persistedRange netip.Prefix, current types.Prefix) bool {
    cur, err := netip.ParsePrefix(current.String())
    if err != nil { return false }
    return persistedRange == cur
}

When it happens

Trigger: Calling Restore (e.g. from an IPAM backing store like a KVstore-backed allocator) with persisted allocation data whose network/prefix does not equal the allocator's current range, typically after the node's allocated CIDR changed.

Common situations: Operator changed node's PodCIDR or the daemon's --cluster-ipv4-cidr / node IPAM pool between restarts; restoring a stale allocation dump from etcd/kvstore after re-configuration; moving a node between IPAM pools.

Related errors

• not ready
• no cilium agent pods found
• unable to detect minimum Cilium version
• unable to initialize IPv4 allocator: %w
• unable to initialize IPv6 allocator: %w

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