{"record":{"id":"d02157788b2cf837","repo":"cilium/cilium","slug":"replacing-maps-from-registry-w","errorCode":null,"errorMessage":"replacing maps from registry: %w","messagePattern":"replacing maps from registry: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/bpf/collection.go","lineNumber":223,"sourceCode":"\t}\n\n\tif err := checkUnspecifiedPrograms(spec); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"checking for unspecified programs: %w\", err)\n\t}\n\n\topts.populateMapReplacements()\n\n\tlogger.Debug(\"Loading Collection into kernel\",\n\t\tlogfields.MapRenames, opts.MapRenames,\n\t\tlogfields.Constants, printConstants(opts.Constants),\n\t)\n\n\t// Copy spec so the modifications below don't affect the input parameter,\n\t// allowing the spec to be safely re-used by the caller.\n\tspec = spec.Copy()\n\n\tif err := patchMaps(spec, opts.MapRegistry); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"replacing maps from registry: %w\", err)\n\t}\n\n\t// Handle BPF_F_RDONLY_PROG flag compatibility for pinned maps before loading.\n\t// This ensures BPF programs can reuse existing pinned maps during upgrades\n\t// where the flag state differs between old and new versions.\n\tif err := adjustMapFlagsForUpgrade(logger, spec, &opts.CollectionOptions); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"adjusting map flags for upgrade: %w\", err)\n\t}\n\n\tif err := renameMaps(spec, opts.MapRenames); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"renaming maps: %w\", err)\n\t}\n\n\tif err := applyConstants(spec, opts.Constants); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"applying variable overrides: %w\", err)\n\t}\n\n\treach, err := computeReachability(spec)","sourceCodeStart":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/bpf/collection.go#L205-L241","documentation":"During LoadCollection, patchMaps looks up MapSpecPatch entries in the provided MapRegistry for every map in the spec and applies them. This wrapper error is returned when a registry lookup or patch application fails for a map; the %w wraps the underlying error, which includes the map name via patchMaps' own wrapping (\"getting MapSpec patch %s\"). A nil registry is a no-op, so this only fires when a MapRegistry was supplied.","triggerScenarios":"Passing opts.MapRegistry to LoadCollection/LoadAndAssign where the registry returns an error other than registry.ErrMapNotFound for one of the spec's maps — e.g. a lookup failure, a malformed patch, or an internal registry error when resolving the patch for map name <name>.","commonSituations":"A MapRegistry was misconfigured or its backing map definitions failed to resolve (e.g. map not registered correctly, registry populated from a partially initialized state); patch objects registered for map names that conflict with the compiled ELF; concurrent access to a registry without proper initialization during agent bootstrap.","solutions":["Read the wrapped error to identify the map name whose patch lookup failed and check how that name was registered in the registry.MapRegistry.","Ensure MapRegistry is fully populated (all maps registered) before calling LoadCollection — register maps before agent bootstrap proceeds.","Verify the registered MapSpecPatch is valid and applicable to the map in the ELF; fix or remove the bad patch registration.","If the map should not be patched, remove it from the registry or rely on the ErrMapNotFound skip path by not registering a patch for it."],"exampleFix":"// before: registry created but maps registered lazily/after load\nreg := registry.NewMapRegistry(nil)\ngo registerMaps(reg)\n_, _, err := bpf.LoadCollection(logger, spec, &bpf.CollectionOptions{MapRegistry: reg})\n\n// after: fully populate the registry before loading\nreg := registry.NewMapRegistry(nil)\nregisterMaps(reg) // synchronous, before load\n_, _, err := bpf.LoadCollection(logger, spec, &bpf.CollectionOptions{MapRegistry: reg})","handlingStrategy":"validation","validationCode":"func validateMapRegistry(reg *registry.MapRegistry, spec *ebpf.CollectionSpec) error {\n\tif reg == nil {\n\t\treturn nil\n\t}\n\tfor name := range spec.Maps {\n\t\tif _, err := reg.GetPatch(name); err != nil && !errors.Is(err, registry.ErrMapNotFound) {\n\t\t\treturn fmt.Errorf(\"registry cannot patch map %s: %w\", name, err)\n\t\t}\n\t}\n\treturn nil\n}\n// call before LoadCollection:\n// if err := validateMapRegistry(opts.MapRegistry, spec); err != nil { return err }","typeGuard":"func registryReady(reg *registry.MapRegistry) bool {\n\treturn reg == nil || reg != nil && len(specMapsCovered(reg)) >= 0 // registry is optional; nil is a valid no-op\n}","tryCatchPattern":"_, _, err := bpf.LoadCollection(logger, spec, opts)\nif err != nil && strings.Contains(err.Error(), \"replacing maps from registry\") {\n\treturn fmt.Errorf(\"map registry misconfigured for this ELF; check registrations: %w\", err)\n}","preventionTips":["Populate the MapRegistry fully and synchronously before any LoadCollection call during agent bootstrap.","Keep registry map names in sync with the compiled ELF; add a startup consistency check.","Treat registry.ErrMapNotFound as the only legitimate skip case; log any other lookup error at registration time."],"tags":["ebpf","go","map-registry","configuration"],"backgroundTag":"ebpf-map-registry-patch-failure","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}