cilium/cilium · error

multicast not enabled

Error message

multicast not enabled

What it means

getMulticastGroupMap tries to open the pinned multicast group outer map (GroupOuter4MapName). If the open fails with fs.ErrNotExist it means the pinned BPF map file is absent, i.e. multicast support was not enabled in the Cilium agent, so the CLI reports 'multicast not enabled'.

Source

Thrown at cilium-dbg/cmd/bpf_multicast_groups.go:136

		}

		groupV4Map, err := getMulticastGroupMap(log)
		if err != nil {
			Fatalf("failed to get multicast bpf map: %s", err)
		}

		err = groupV4Map.Delete(group)
		if err != nil {
			Fatalf("Error deleting multicast group: %s", err)
		}
	},
}

func getMulticastGroupMap(logger *slog.Logger) (*maps_multicast.GroupV4OuterMap, error) {
	groupV4Map, err := maps_multicast.OpenGroupV4OuterMap(logger, maps_multicast.GroupOuter4MapName)
	if err != nil {
		if errors.Is(err, fs.ErrNotExist) {
			return nil, fmt.Errorf("multicast not enabled")
		}
		return nil, fmt.Errorf("cannot open multicast bpf maps: %w", err)
	}

	return groupV4Map, nil
}

func parseMulticastGroupArgs(args []string) (netip.Addr, error) {
	if len(args) != 1 {
		return netip.Addr{}, fmt.Errorf("expecting group IP as argument, got %d arguments", len(args))
	}

	group, err := netip.ParseAddr(args[0])
	if err != nil {
		return netip.Addr{}, fmt.Errorf("invalid IP address format: %w", err)
	}

	// check group is multicast and ipv4 address

View on GitHub (pinned to ac7b90affa)

Solutions

1. Enable multicast in the Cilium agent config (Helm value / ConfigMap) and restart the agent so the pinned maps are created
2. Verify the map pin exists: `ls /sys/fs/bpf/tc/globals/cilium_mc_group_v4*` or `bpftool map list | grep -i multicast`
3. Check the Cilium version supports the multicast BPF maps feature; upgrade if needed
4. Confirm cilium-dbg is pointing at the correct node/agent where multicast is enabled

Example fix

// before: run multicast CLI against agent with feature disabled
cilium-dbg bpf multicast groups list
// after: enable the feature first, then run
helm upgrade cilium cilium/cilium --set multicast.enabled=true
cilium-dbg bpf multicast groups list

// check the pinned multicast group map exists before invoking the command
if ! ls /sys/fs/bpf/tc/globals/cilium_mc_group_v4* >/dev/null 2>&1; then
  echo "multicast not enabled: enable the multicast option in the Cilium agent config and restart"
fi

groupMap, err := getMulticastGroupMap(logger)
if err != nil {
	if errors.Is(err, fs.ErrNotExist) || strings.Contains(err.Error(), "multicast not enabled") {
		return fmt.Errorf("multicast is disabled on this agent; set the multicast config option and restart Cilium")
	}
	return err
}

When it happens

Trigger: Running any `cilium-dbg bpf multicast ...` command (groups list, subscribers add/remove/list) on a node where the multicast feature flag is off, so OpenGroupV4OuterMap cannot find the pinned map file.

Common situations: Multicast not enabled via the Cilium Helm/ConfigMap option (e.g. multicast.enabled or enableMulticast-related config); running the CLI against an older Cilium version without the feature; checking maps on a node before the agent created them at startup.

Related errors

• cannot open multicast bpf maps: %w
• failed to lookup multicast group %s: %w
• failed to list multicast subscribers for group %s: %w
• cannot open inner map with id %d: %w
• dumping inner map id %d: %w

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