cilium/cilium · error

open map by id: %w

Error message

open map by id: %w

What it means

This error wraps a failure from ebpf.NewMapFromID when the collector opens a BPF map by ID during visitMap. Only os.ErrNotExist (map already gone) is tolerated and skipped; any other kernel error (typically EPERM) surfaces wrapped here.

Source

Thrown at pkg/metrics/bpf.go:148

		}
	}

	return nil
}

// visitMap opens the given map by id and collects its memory usage.
func (v *bpfVisitor) visitMap(id ebpf.MapID) error {
	if _, ok := v.mapsVisited[id]; ok {
		return nil
	}
	v.mapsVisited[id] = struct{}{}

	m, err := ebpf.NewMapFromID(id)
	if errors.Is(err, os.ErrNotExist) {
		return nil
	}
	if err != nil {
		return fmt.Errorf("open map by id: %w", err)
	}
	defer m.Close()

	info, err := m.Info()
	if err != nil {
		return fmt.Errorf("get map info: %w", err)
	}

	// Maps with BPF_F_NO_PREALLOC set (like LPMTrie) report a size of 0 when
	// empty. Zero memory usage can be valid for a map.
	mem, _ := info.Memlock()

	v.maps++
	v.mapBytes += mem

	return nil
}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Run the agent with the necessary BPF capabilities or as root.
2. Read the wrapped errno via errors.Unwrap to pinpoint the kernel failure (mount bpffs, upgrade kernel).
3. Confirm kernel >= 4.13 for BPF_MAP_GET_FD_BY_ID support.
4. Retry collection on transient concurrent-removal errors.

caps, _ := capabilities.NewPidFile("/proc/self/status")
if !caps.Get(capabilities.BPF) || !caps.Get(capabilities.SYS_ADMIN) {
    log.Warn("BPF map access will be denied; disabling map metrics")
}

func isMapOpenPermissionErr(err error) bool {
    var errno syscall.Errno
    return errors.As(err, &errno) && errno == syscall.EPERM
}

m, err := ebpf.NewMapFromID(id)
if err != nil {
    if errors.Is(err, os.ErrNotExist) {
        return nil // already gone, safe
    }
    log.Warn("cannot open map for metrics; skipping", "id", id, "err", err)
    return nil // degrade instead of failing the whole scrape
}

When it happens

Trigger: bpfVisitor.visitMap calls ebpf.NewMapFromID(id) for a map ID discovered via a program's info.MapIDs(); the kernel refuses to return an FD for the map for reasons other than nonexistence.

Common situations: Running without CAP_BPF/CAP_SYS_ADMIN; kernel < 4.13 lacking BPF_MAP_GET_FD_BY_ID; transient races where the map is torn down while being visited (usually handled as ErrNotExist).

Related errors

• get map info: %w
• open program by id: %w
• get program info: %w
• querying program stats: %w
• failed to query for multicast group: %w

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