cilium/cilium · error

replacing maps from registry: %w

Error message

replacing maps from registry: %w

What it means

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.

Source

Thrown at pkg/bpf/collection.go:223

	}

	if err := checkUnspecifiedPrograms(spec); err != nil {
		return nil, nil, fmt.Errorf("checking for unspecified programs: %w", err)
	}

	opts.populateMapReplacements()

	logger.Debug("Loading Collection into kernel",
		logfields.MapRenames, opts.MapRenames,
		logfields.Constants, printConstants(opts.Constants),
	)

	// Copy spec so the modifications below don't affect the input parameter,
	// allowing the spec to be safely re-used by the caller.
	spec = spec.Copy()

	if err := patchMaps(spec, opts.MapRegistry); err != nil {
		return nil, nil, fmt.Errorf("replacing maps from registry: %w", err)
	}

	// Handle BPF_F_RDONLY_PROG flag compatibility for pinned maps before loading.
	// This ensures BPF programs can reuse existing pinned maps during upgrades
	// where the flag state differs between old and new versions.
	if err := adjustMapFlagsForUpgrade(logger, spec, &opts.CollectionOptions); err != nil {
		return nil, nil, fmt.Errorf("adjusting map flags for upgrade: %w", err)
	}

	if err := renameMaps(spec, opts.MapRenames); err != nil {
		return nil, nil, fmt.Errorf("renaming maps: %w", err)
	}

	if err := applyConstants(spec, opts.Constants); err != nil {
		return nil, nil, fmt.Errorf("applying variable overrides: %w", err)
	}

	reach, err := computeReachability(spec)

View on GitHub (pinned to ac7b90affa)

Solutions

1. Read the wrapped error to identify the map name whose patch lookup failed and check how that name was registered in the registry.MapRegistry.
2. Ensure MapRegistry is fully populated (all maps registered) before calling LoadCollection — register maps before agent bootstrap proceeds.
3. Verify the registered MapSpecPatch is valid and applicable to the map in the ELF; fix or remove the bad patch registration.
4. 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.

Example fix

// before: registry created but maps registered lazily/after load
reg := registry.NewMapRegistry(nil)
go registerMaps(reg)
_, _, err := bpf.LoadCollection(logger, spec, &bpf.CollectionOptions{MapRegistry: reg})

// after: fully populate the registry before loading
reg := registry.NewMapRegistry(nil)
registerMaps(reg) // synchronous, before load
_, _, err := bpf.LoadCollection(logger, spec, &bpf.CollectionOptions{MapRegistry: reg})

func validateMapRegistry(reg *registry.MapRegistry, spec *ebpf.CollectionSpec) error {
	if reg == nil {
		return nil
	}
	for name := range spec.Maps {
		if _, err := reg.GetPatch(name); err != nil && !errors.Is(err, registry.ErrMapNotFound) {
			return fmt.Errorf("registry cannot patch map %s: %w", name, err)
		}
	}
	return nil
}
// call before LoadCollection:
// if err := validateMapRegistry(opts.MapRegistry, spec); err != nil { return err }

func registryReady(reg *registry.MapRegistry) bool {
	return reg == nil || reg != nil && len(specMapsCovered(reg)) >= 0 // registry is optional; nil is a valid no-op
}

_, _, err := bpf.LoadCollection(logger, spec, opts)
if err != nil && strings.Contains(err.Error(), "replacing maps from registry") {
	return fmt.Errorf("map registry misconfigured for this ELF; check registrations: %w", err)
}

When it happens

Trigger: 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>.

Common situations: 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.

Related errors

• renaming maps: %w
• must not be empty
• must not be more than 32 characters
• must consist of lower case alphanumeric characters and '-',
• registry has already been started

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