cilium/cilium · warning

failed to close bpf map: %w

Error message

failed to close bpf map: %w

What it means

lxcmap's close() wraps any failure from bpfMap.Close(), which releases the file descriptor of the BPF endpoints map. Close rarely fails; when it does, it indicates an OS-level problem closing the fd or an already-closed/invalid map handle.

Source

Thrown at pkg/maps/lxcmap/lxcmap.go:94

	m, err := bpf.OpenMap(bpf.MapPath(logger, mapName), &EndpointKey{}, &EndpointInfo{})
	if err != nil {
		return nil, fmt.Errorf("failed to open map: %w", err)
	}

	return &lxcMap{bpfMap: m}, nil
}

func (m *lxcMap) init() error {
	if err := m.bpfMap.OpenOrCreate(); err != nil {
		return fmt.Errorf("failed to init bpf map: %w", err)
	}

	return nil
}

func (m *lxcMap) close() error {
	if err := m.bpfMap.Close(); err != nil {
		return fmt.Errorf("failed to close bpf map: %w", err)
	}

	return nil
}

const (
	// EndpointFlagHost indicates that this endpoint represents the host
	EndpointFlagHost = 1

	// EndpointFlagAtHostNS indicates that this endpoint is located at the host networking
	// namespace
	EndpointFlagAtHostNS = 2

	// EndpointFlagSkipMasqueradeV4 indicates that this endpoint should skip IPv4 masquerade for remote traffic
	EndpointFlagSkipMasqueradeV4 = 4

	// EndpointFlagSkipMasqueradeV6 indicates that this endpoint should skip IPv6 masquerade for remote traffic
	EndpointFlagSkipMasqueradeV6 = 8

View on GitHub (pinned to ac7b90affa)

Solutions

1. Check the wrapped error; if it is 'file already closed', fix double-close ownership so only one component closes the map.
2. Ensure shutdown ordering: close the lxc map after all users (endpoint restore, datapath) have stopped.
3. Log and continue for best-effort shutdown, since resources are reclaimed at process exit anyway.

if err := m.close(); err != nil {
	if strings.Contains(err.Error(), "already closed") {
		return nil // idempotent shutdown
	}
	log.Warn("map close failed during shutdown", "err", err)
	return nil
}

When it happens

Trigger: Calling lxcMap.close() when bpfMap.Close() returns an error: double-close of the underlying map, the fd was invalidated, or an underlying ebpf library close failure (e.g. after the map was already released elsewhere).

Common situations: Shutdown ordering bugs where another component closed or unpinned the map first; lifetime-management bugs sharing the map across hive cells; tests tearing down maps multiple times.

Related errors

• failed to close bpf map: %w
• cannot open inner map with id %d: %w
• dumping inner map id %d: %w
• multicast not enabled
• cannot open multicast bpf maps: %w

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