What causes "loading pinned map %s: %w" in cilium/cilium?

Create/open-and-pin the map first (OpenOrCreate/Recreate) before calling Open or dependent ops like Update/Delete

loading pinned map %s: %w

Error message

loading pinned map %s: %w

What it means

open() loads the map pinned at the bpffs path with ebpf.LoadPinnedMap and wraps any failure. The map file does not exist at the path, is not a valid BPF map pin, or the process lacks permission to open it. Callers like Update/Delete/ClearAll go through this open path implicitly, so a missing pin surfaces here.

Source

Thrown at pkg/bpf/map_linux.go:682

	return m.open()
}

// open opens the BPF map. It is identical to Open() but should be used when
// m.lock is already held. open() may only be used if m.lock is held for
// writing.
func (m *Map) open() error {
	if m.m != nil {
		return nil
	}

	if err := m.setPathIfUnset(); err != nil {
		return err
	}

	em, err := ebpf.LoadPinnedMap(m.path, nil)
	if err != nil {
		return fmt.Errorf("loading pinned map %s: %w", m.path, err)
	}

	m.m = em

	m.updateMetrics()
	registerMap(m.Logger, m.path, m)

	return nil
}

func (m *Map) Close() error {
	m.lock.Lock()
	defer m.lock.Unlock()

	if m.enableSync {
		mapControllers.RemoveController(m.controllerName())
	}

View on GitHub (pinned to ac7b90affa)

Solutions

Create/open-and-pin the map first (OpenOrCreate/Recreate) before calling Open or dependent ops like Update/Delete
Verify the pin exists: ls -l at m.path and confirm the bpffs mount is active
Check the configured path matches the one used at pin time (no config drift between versions)
Run with enough privileges to open pins under /sys/fs/bpf

Example fix

// before
m := bpf.NewMap(logger, "drops", "/sys/fs/bpf/drops", spec, val)
m.Update(key, val) // fails: loading pinned map /sys/fs/bpf/drops: no such file or directory
// after
if err := m.OpenOrCreate(); err != nil { return err }
m.Update(key, val)

Defensive patterns

Strategy: fallback

Validate before calling

if _, err := os.Stat(path); errors.Is(err, fs.ErrNotExist) {
    // pin missing: create it first via OpenOrCreate before Update/Delete
}
if err := exec.Command("mountpoint", "-q", "/sys/fs/bpf").Run(); err != nil {
    // bpffs not mounted
}

Try / catch

if err := m.Open(); err != nil {
    if errors.Is(err, fs.ErrNotExist) {
        if err := m.OpenOrCreate(); err != nil { return err } // fallback: create+pin
        return nil
    }
    return fmt.Errorf("loading pinned map: %w", err)
}

Prevention

Pin maps at startup before any read/update paths run
Keep pin paths in one shared constant/config to prevent drift
Verify bpffs is mounted in entrypoint/systemd setup
On fresh nodes, always prefer OpenOrCreate over Open

When it happens

Trigger: Map.Open(), Update(), Delete(), DeleteAll(), ClearAll() or resolveErrors() when the map was never created/pinned at m.path, the pin path changed between runs, or the path holds a different object type (e.g. a pinned program).

Common situations: Fresh node where the pinning process hasn't run yet; bpffs not mounted at the expected directory; path mismatch after config change or image upgrade; pin removed by a concurrent cleanup while map metadata still references it.

Related errors

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