cilium/cilium · critical

initializing IPv6 masquerading map: %w

Error message

initializing IPv6 masquerading map: %w

What it means

Returned in the same ip-masq-maps cell OnStart hook when the IPv6 ip-masq-agent BPF map (cilium_ipmasq_v6) cannot be opened or created via IPMasq6Map(...).OpenOrCreate(). It wraps the underlying bpf error and aborts agent startup. Only triggered when EnableIPMasqAgent and EnableIPv6Masquerade are both true.

Source

Thrown at pkg/maps/ipmasq/cell.go:43

	Lifecycle       cell.Lifecycle
	MetricsRegistry *metrics.Registry
}

func newIPMasqMaps(p ipMasqMapsParams) bpf.MapOut[*IPMasqBPFMap] {
	m := &IPMasqBPFMap{MetricsRegistry: p.MetricsRegistry}

	p.Lifecycle.Append(cell.Hook{
		OnStart: func(cell.HookContext) error {
			if option.Config.EnableIPMasqAgent {
				if option.Config.EnableIPv4Masquerade {
					if err := IPMasq4Map(p.MetricsRegistry).OpenOrCreate(); err != nil {
						return fmt.Errorf("initializing IPv4 masquerading map: %w", err)
					}
				}
				if option.Config.EnableIPv6Masquerade {
					if err := IPMasq6Map(p.MetricsRegistry).OpenOrCreate(); err != nil {
						return fmt.Errorf("initializing IPv6 masquerading map: %w", err)
					}
				}
			}
			return nil
		},
		OnStop: func(cell.HookContext) error {
			// No clean-up required for the ip-masq-agent maps at shutdown.
			return nil
		},
	})

	return bpf.NewMapOut(m)
}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Check IPv6 is enabled on the host: sysctl net.ipv6.conf.all.disable_ipv6 (must be 0) and no ipv6.disable=1 in kernel cmdline.
2. If IPv6 masquerading is not needed, start with --enable-ipv6-masquerade=false.
3. Ensure /sys/fs/bpf is mounted bpf and writable, and the agent runs with CAP_BPF/CAP_SYS_ADMIN.
4. Delete stale pinned cilium_ipmasq_v6 maps from prior versions and restart.
5. Inspect the wrapped inner error for the exact errno (ENOENT/EPERM/EAFNOSUPPORT).

Example fix

// before: kernel cmdline has ipv6.disable=1
// error: initializing IPv6 masquerading map: ...

// after: enable IPv6 or turn off the flag
$ grubby --update-kernel=ALL --remove-args="ipv6.disable=1"  # or
$ cilium-agent --enable-ip-masq-agent=true --enable-ipv6-masquerade=false

// Verify IPv6 availability before enabling IPv6 masquerade + masq-agent.
func validateIPv6MasqEnv() error {
    if _, err := os.Stat("/proc/net/if_inet6"); err != nil {
        return errors.New("IPv6 is disabled on this host (ipv6.disable=1 or module missing)")
    }
    if data, err := os.ReadFile("/proc/sys/net/ipv6/conf/all/disable_ipv6"); err == nil && strings.TrimSpace(string(data)) == "1" {
        return errors.New("net.ipv6.conf.all.disable_ipv6=1")
    }
    return nil
}

func ipv6Enabled() bool {
    addrs, err := net.InterfaceAddrs()
    if err != nil {
        return false
    }
    for _, a := range addrs {
        if ipnet, ok := a.(*net.IPNet); ok && ipnet.IP.To4() == nil && ipnet.IP.To16() != nil {
            return true
        }
    }
    return false
}

if err := IPMasq6Map(p.MetricsRegistry).OpenOrCreate(); err != nil {
    var errno unix.Errno
    if errors.As(err, &errno) && errno == unix.EAFNOSUPPORT {
        return fmt.Errorf("kernel reports no IPv6 support; disable --enable-ipv6-masquerade: %w", err)
    }
    return fmt.Errorf("initializing IPv6 masquerading map: %w", err)
}

When it happens

Trigger: Agent startup with --enable-ip-masq-agent=true and --enable-ipv6-masquerade=true; IPMasq6Map(...).OpenOrCreate() fails because IPv6 is disabled at the host/kernel level (ipv6.disable=1), bpffs is missing or read-only, capabilities are insufficient, or a pinned cilium_ipmasq_v6 map has an incompatible layout.

Common situations: Host booted with ipv6.disable=1 kernel parameter while IPv6 masquerade + masq-agent flags are enabled; missing bpffs mount or unprivileged container; stale pinned cilium_ipmasq_v6 from an older Cilium version; kernel without IPv6 BPF map support.

Related errors

• initializing IPv4 masquerading map: %w
• failed to init lxc map: %w
• failed to delete all entries in lxc map: %w
• egress gateway requires an IPv4 underlay
• failed to write auth information to BPF map: %w

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