{"record":{"id":"28e9cc56e8ee9bd3","repo":"cilium/cilium","slug":"open-map-by-id-w","errorCode":null,"errorMessage":"open map by id: %w","messagePattern":"open map by id: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/metrics/bpf.go","lineNumber":148,"sourceCode":"\t\t}\n\t}\n\n\treturn nil\n}\n\n// visitMap opens the given map by id and collects its memory usage.\nfunc (v *bpfVisitor) visitMap(id ebpf.MapID) error {\n\tif _, ok := v.mapsVisited[id]; ok {\n\t\treturn nil\n\t}\n\tv.mapsVisited[id] = struct{}{}\n\n\tm, err := ebpf.NewMapFromID(id)\n\tif errors.Is(err, os.ErrNotExist) {\n\t\treturn nil\n\t}\n\tif err != nil {\n\t\treturn fmt.Errorf(\"open map by id: %w\", err)\n\t}\n\tdefer m.Close()\n\n\tinfo, err := m.Info()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"get map info: %w\", err)\n\t}\n\n\t// Maps with BPF_F_NO_PREALLOC set (like LPMTrie) report a size of 0 when\n\t// empty. Zero memory usage can be valid for a map.\n\tmem, _ := info.Memlock()\n\n\tv.maps++\n\tv.mapBytes += mem\n\n\treturn nil\n}\n","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/metrics/bpf.go#L130-L166","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Run the agent with the necessary BPF capabilities or as root.","Read the wrapped errno via errors.Unwrap to pinpoint the kernel failure (mount bpffs, upgrade kernel).","Confirm kernel >= 4.13 for BPF_MAP_GET_FD_BY_ID support.","Retry collection on transient concurrent-removal errors."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"caps, _ := capabilities.NewPidFile(\"/proc/self/status\")\nif !caps.Get(capabilities.BPF) || !caps.Get(capabilities.SYS_ADMIN) {\n    log.Warn(\"BPF map access will be denied; disabling map metrics\")\n}","typeGuard":"func isMapOpenPermissionErr(err error) bool {\n    var errno syscall.Errno\n    return errors.As(err, &errno) && errno == syscall.EPERM\n}","tryCatchPattern":"m, err := ebpf.NewMapFromID(id)\nif err != nil {\n    if errors.Is(err, os.ErrNotExist) {\n        return nil // already gone, safe\n    }\n    log.Warn(\"cannot open map for metrics; skipping\", \"id\", id, \"err\", err)\n    return nil // degrade instead of failing the whole scrape\n}","preventionTips":["Grant CAP_BPF/CAP_SYS_ADMIN to the process.","Ensure kernel >= 4.13 for map-by-ID support.","Do not fail entire metric scrapes on individual map access errors."],"tags":["bpf","ebpf","maps","permissions","kernel"],"backgroundTag":"bpf-map-open-failed","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}