cilium/cilium · error

MapSpec not found

Error message

MapSpec not found

What it means

ErrMapNotFound is a sentinel error of the pkg/maps/registry MapRegistry indicating no [ebpf.MapSpec] is registered under the requested name. It is returned by Get, GetPatch, patchMaps, Modify, and TestMapRegistry when the given map name does not match any registered spec. It signals a name mismatch or a missing cell contribution, not a datapath/pinning failure.

Source

Thrown at pkg/maps/registry/registry.go:24

import (
	_ "embed"
	"errors"
	"fmt"
	"log/slog"

	"github.com/cilium/ebpf"

	_ "github.com/cilium/hive/cell"

	"github.com/cilium/cilium/pkg/datapath/maps"
	"github.com/cilium/cilium/pkg/lock"
	"github.com/cilium/cilium/pkg/logging/logfields"
)

var (
	ErrStarted     = errors.New("registry has already been started")
	ErrNotStarted  = errors.New("registry has not yet been started")
	ErrMapNotFound = errors.New("MapSpec not found")
)

// MapRegistry contains [ebpf.MapSpec]s for all pinned maps in the datapath.
//
// The registry allows Cells to provide [MapSpecPatch]es during Hive
// construction, e.g. for changing MaxEntries of a map based on configuration
// parameters. Only select fields can be modified, see [MapSpecPatch] for
// details.
//
// Once the registry has been started, MapSpecs can only be retrieved but
// not modified. Any packages which need to create maps at runtime should
// obtain the MapSpecs from this registry.
type MapRegistry struct {
	l *slog.Logger

	mu      lock.Mutex
	started bool

View on GitHub (pinned to ac7b90affa)

Solutions

1. Verify the exact map name against the MapSpec registrations (compare with errors.Is(err, registry.ErrMapNotFound) and log the requested name).
2. Register the missing MapSpec or add the cell that contributes it to the Hive.
3. Update the map name after a cilium upgrade where the map was renamed or deleted.
4. Use GetPatch only for maps known to exist; check presence with Get first.

Example fix

// before
patch := reg.GetPatch("cilium_ipcache_v2_old") // ErrMapNotFound after rename
// after
spec, err := reg.Get("cilium_ipcache")
if errors.Is(err, registry.ErrMapNotFound) {
    return fmt.Errorf("map %q not registered; available maps must be contributed by a cell", "cilium_ipcache")
}

// check presence before patching
if _, err := reg.Get(mapName); errors.Is(err, registry.ErrMapNotFound) {
    return fmt.Errorf("cannot patch unknown map %q", mapName)
}

func mapExists(r *registry.MapRegistry, name string) bool {
    _, err := r.Get(name)
    return !errors.Is(err, registry.ErrMapNotFound)
}

patch, err := reg.GetPatch(mapName)
if errors.Is(err, registry.ErrMapNotFound) {
    log.Warnf("map %q not registered, skipping patch", mapName)
    return nil
}
if err != nil { return err }

When it happens

Trigger: Get(name)/GetPatch(name) with a name not in the registry; Modify() or patchMaps() targeting a MapSpec that no cell provided; TestMapRegistry asserting on an unknown map name.

Common situations: Typo or wrong prefix in the map name; a map was removed/renamed in a newer cilium version while external code still patches the old name; a cell providing the MapSpecPatch is not included in the Hive.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• ErrMapNotFound
• registry has already been started
• registry has not yet been started
• failed to lookup authkey: %w
• assigning eBPF objects to %T: %w

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