{"record":{"id":"b1de9efba5e72037","repo":"cilium/cilium","slug":"initializing-ipv6-masquerading-map-w","errorCode":null,"errorMessage":"initializing IPv6 masquerading map: %w","messagePattern":"initializing IPv6 masquerading map: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/maps/ipmasq/cell.go","lineNumber":43,"sourceCode":"\n\tLifecycle       cell.Lifecycle\n\tMetricsRegistry *metrics.Registry\n}\n\nfunc newIPMasqMaps(p ipMasqMapsParams) bpf.MapOut[*IPMasqBPFMap] {\n\tm := &IPMasqBPFMap{MetricsRegistry: p.MetricsRegistry}\n\n\tp.Lifecycle.Append(cell.Hook{\n\t\tOnStart: func(cell.HookContext) error {\n\t\t\tif option.Config.EnableIPMasqAgent {\n\t\t\t\tif option.Config.EnableIPv4Masquerade {\n\t\t\t\t\tif err := IPMasq4Map(p.MetricsRegistry).OpenOrCreate(); err != nil {\n\t\t\t\t\t\treturn fmt.Errorf(\"initializing IPv4 masquerading map: %w\", err)\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tif option.Config.EnableIPv6Masquerade {\n\t\t\t\t\tif err := IPMasq6Map(p.MetricsRegistry).OpenOrCreate(); err != nil {\n\t\t\t\t\t\treturn fmt.Errorf(\"initializing IPv6 masquerading map: %w\", err)\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn nil\n\t\t},\n\t\tOnStop: func(cell.HookContext) error {\n\t\t\t// No clean-up required for the ip-masq-agent maps at shutdown.\n\t\t\treturn nil\n\t\t},\n\t})\n\n\treturn bpf.NewMapOut(m)\n}\n","sourceCodeStart":25,"sourceCodeEnd":57,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/maps/ipmasq/cell.go#L25-L57","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","If IPv6 masquerading is not needed, start with --enable-ipv6-masquerade=false.","Ensure /sys/fs/bpf is mounted bpf and writable, and the agent runs with CAP_BPF/CAP_SYS_ADMIN.","Delete stale pinned cilium_ipmasq_v6 maps from prior versions and restart.","Inspect the wrapped inner error for the exact errno (ENOENT/EPERM/EAFNOSUPPORT)."],"exampleFix":"// before: kernel cmdline has ipv6.disable=1\n// error: initializing IPv6 masquerading map: ...\n\n// after: enable IPv6 or turn off the flag\n$ grubby --update-kernel=ALL --remove-args=\"ipv6.disable=1\"  # or\n$ cilium-agent --enable-ip-masq-agent=true --enable-ipv6-masquerade=false","handlingStrategy":"validation","validationCode":"// Verify IPv6 availability before enabling IPv6 masquerade + masq-agent.\nfunc validateIPv6MasqEnv() error {\n    if _, err := os.Stat(\"/proc/net/if_inet6\"); err != nil {\n        return errors.New(\"IPv6 is disabled on this host (ipv6.disable=1 or module missing)\")\n    }\n    if data, err := os.ReadFile(\"/proc/sys/net/ipv6/conf/all/disable_ipv6\"); err == nil && strings.TrimSpace(string(data)) == \"1\" {\n        return errors.New(\"net.ipv6.conf.all.disable_ipv6=1\")\n    }\n    return nil\n}","typeGuard":"func ipv6Enabled() bool {\n    addrs, err := net.InterfaceAddrs()\n    if err != nil {\n        return false\n    }\n    for _, a := range addrs {\n        if ipnet, ok := a.(*net.IPNet); ok && ipnet.IP.To4() == nil && ipnet.IP.To16() != nil {\n            return true\n        }\n    }\n    return false\n}","tryCatchPattern":"if err := IPMasq6Map(p.MetricsRegistry).OpenOrCreate(); err != nil {\n    var errno unix.Errno\n    if errors.As(err, &errno) && errno == unix.EAFNOSUPPORT {\n        return fmt.Errorf(\"kernel reports no IPv6 support; disable --enable-ipv6-masquerade: %w\", err)\n    }\n    return fmt.Errorf(\"initializing IPv6 masquerading map: %w\", err)\n}","preventionTips":["Set --enable-ipv6-masquerade=false when the host has IPv6 disabled.","Remove ipv6.disable=1 from the kernel cmdline if IPv6 masquerading is required.","Verify /proc/net/if_inet6 exists before enabling IPv6 features.","Keep bpffs mounted and privileges granted as for the v4 map.","Recreate stale cilium_ipmasq_v6 pins after upgrades."],"tags":["ebpf","cilium","bpf-map","ipv6","startup"],"backgroundTag":"bpf-map-open-or-create-failed","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}