cilium/cilium · error

failed to lookup subscriber %s: %w

Error message

failed to lookup subscriber %s: %w

What it means

Generic failure wrapper for the eBPF inner-map Lookup in SubscriberV4InnerMap.Lookup, covering all errors other than ErrKeyNotExist. It signals a real syscall/fd-level failure querying the kernel map, not a missing subscriber.

Source

Thrown at pkg/maps/multicast/subscribermap.go:429

	}

	return nil
}

func (m SubscriberV4InnerMap) Lookup(Src netip.Addr) (*SubscriberV4, error) {
	val := SubscriberV4Val{}

	key, err := NewSubscriberV4KeyFromNetIPAddr(Src)
	if err != nil {
		return nil, err
	}

	err = m.Map.Lookup(key.SAddr, &val)
	if errors.Is(err, ebpf.ErrKeyNotExist) {
		return nil, fmt.Errorf("no subscriber with source address %s: %w", Src.String(), err)
	}
	if err != nil {
		return nil, fmt.Errorf("failed to lookup subscriber %s: %w", Src.String(), err)
	}

	sub, err := val.ToSubsciberV4()
	if err != nil {
		return nil, err
	}

	return sub, nil
}

func (m SubscriberV4InnerMap) Delete(Src netip.Addr) error {
	key, err := NewSubscriberV4KeyFromNetIPAddr(Src)
	if err != nil {
		return err
	}
	return m.Map.Delete(key)
}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Run with adequate privileges (root or CAP_BPF+CAP_PERFMON / CAP_SYS_ADMIN)
2. Inspect the wrapped error's cause (fd state, errno) and verify the map is open
3. Check kernel version and seccomp/LSM policy for bpf syscall denials; verify with `bpftool map list`
4. Ensure shutdown ordering doesn't close maps before in-flight lookups finish

Example fix

// before
return nil, fmt.Errorf("failed to lookup subscriber %s: %w", Src.String(), err)
// after
return nil, fmt.Errorf("failed to lookup subscriber %s (fd=%d): %w", Src.String(), m.FD(), err) // surface cause for diagnosis

sub, err := innerMap.Lookup(src)
if err != nil {
    if errors.Is(err, ebpf.ErrKeyNotExist) { return nil, ErrNotFound }
    return fmt.Errorf("inner map lookup failed: %w", err) // inspect cause: fd, caps, kernel
}

When it happens

Trigger: m.Map.Lookup(key.SAddr, &val) fails with something other than ErrKeyNotExist: invalid/closed map FD, insufficient capabilities, or bpf_map_lookup_elem rejected by the kernel.

Common situations: Agent shutting down (maps closed) while lookups in flight; running without CAP_BPF/CAP_SYS_ADMIN in restricted environments; kernel/seccomp blocking the bpf syscall.

Related errors

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

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