cilium/cilium · error

initializing events map: %w

Error message

initializing events map: %w

What it means

After successfully obtaining the CPU count, the eventsmap cell calls eventsMap.init(cpus) to create the cilium_events perf event ring buffer (one per-CPU perf array). Any failure from init — opening perf events, creating the BPF map, missing perf_event_open support — is wrapped as 'initializing events map'. This aborts the events-map cell's startup.

Source

Thrown at pkg/maps/eventsmap/cell.go:41

var (
	MaxEntries int
)

type Map any

func newEventsMap(lifecycle cell.Lifecycle) bpf.MapOut[Map] {
	eventsMap := &eventsMap{}

	lifecycle.Append(cell.Hook{
		OnStart: func(context cell.HookContext) error {
			cpus, err := ebpf.PossibleCPU()
			if err != nil {
				return fmt.Errorf("failed to get number of possible CPUs: %w", err)
			}
			err = eventsMap.init(cpus)
			if err != nil {
				return fmt.Errorf("initializing events map: %w", err)
			}
			return nil
		},
		OnStop: func(context cell.HookContext) error {
			// We don't currently care for cleaning up.
			return nil
		},
	})

	return bpf.NewMapOut(Map(eventsMap))
}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Read the wrapped inner error (errors.Unwrap / logs) for the root cause
2. Raise the memlock limit: set ulimit -l unlimited or LimitMEMLOCK=infinity in the systemd unit (older kernels)
3. Ensure the container has CAP_BPF, CAP_PERFMON (or CAP_SYS_ADMIN) and isn't blocked by seccomp from perf_event_open
4. Run on a supported kernel (>=4.9; >=5.8 with the new BPF caps) and check perf_event_paranoid settings
5. Reduce the agent's CPU footprint test: run on a host with fewer CPUs to confirm memory pressure was the cause

Example fix

// before (systemd unit)
[Service]
# no memlock config
// after
[Service]
LimitMEMLOCK=infinity
AmbientCapabilities=CAP_BPF CAP_PERFMON CAP_SYS_ADMIN

// shell, before startup
ulimit -l  # must be unlimited or large on kernels <5.11
test -w /proc/sys/kernel/perf_event_paranoid && cat /proc/sys/kernel/perf_event_paranoid
capsh --print | grep -E 'cap_bpf|cap_perfmon|cap_sys_admin'

if err := eventsMap.init(cpus); err != nil {
    var pe ebpf.Error
    if errors.As(err, &pe) {
        // log wrapped perf/map error before aborting
    }
    return fmt.Errorf("initializing events map: %w", err)
}

When it happens

Trigger: eventsMap.init(cpus) returns an error during hive OnStart: e.g. ebpf.NewPerfEventRing failing to create the per-CPU ring buffer, perf_event_open blocked, or map creation/pinning failures.

Common situations: Kernel without BPF_MAP_TYPE_PERF_EVENT_ARRAY support (very old kernels); perf_event_open blocked by seccomp/pod security policies; RLIMIT_MEMLOCK too low to allocate ring buffers on many CPUs; privilege loss (missing CAP_BPF/CAP_PERFMON/CAP_SYS_ADMIN).

Related errors

• failed to get number of possible CPUs: %w
• Encrypt map create failed: %w
• failed to create fragments v4 bpf map: %w
• failed to create fragments v6 bpf map: %w
• program %s has zero memlock

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