cilium/cilium · error

failed to get loopback device

Error message

failed to get loopback device

What it means

ReinstallRoutingRules looks up the loopback device ('lo') from the Cilium internal device table before installing the IPv4 to-proxy routes. If the 'lo' device is not present in the table while IPv4 and the proxy are enabled, it refuses to install a default route into the to-proxy table pointing at a nil device and returns this error. It indicates the node's device inventory observed by Cilium is incomplete or not yet populated.

Source

Thrown at pkg/proxy/routes.go:57

// to route packets to and from the L7 proxy. Or removes rules if the proxy is disabled.
func (p *Proxy) ReinstallRoutingRules(ctx context.Context, mtu int, ipsecEnabled, wireguardEnabled bool) error {
	defer p.routeManager.FinalizeInitializer(p.routeInitializer)

	localNode, err := p.localNodeStore.Get(ctx)
	if err != nil {
		return fmt.Errorf("failed to retrieve local node: %w", err)
	}

	fromIngressProxy, fromEgressProxy, mtu := requireFromProxyRoutes(ipsecEnabled, wireguardEnabled, mtu)

	rxn := p.db.ReadTxn()
	hostDevice, _, hostDeviceFound := p.devices.Get(rxn, tables.DeviceByName(defaults.HostDevice))
	ciliumNetDevice, _, ciliumNetDeviceFound := p.devices.Get(rxn, tables.DeviceByName(defaults.SecondHostDevice))
	lo, _, loFound := p.devices.Get(rxn, tables.DeviceByName("lo"))

	if option.Config.EnableIPv4 && p.enabled {
		if !loFound {
			return fmt.Errorf("failed to get loopback device")
		}
		if err := installToProxyRoutesIPv4(lo, p.routeManager, p.routeOwner); err != nil {
			return err
		}

		if fromIngressProxy || fromEgressProxy {
			if !hostDeviceFound {
				return fmt.Errorf("failed to get host device %s", defaults.HostDevice)
			}
			internalIP, _ := netipx.FromStdIP(localNode.GetCiliumInternalIP(false))
			if err := installFromProxyRoutesIPv4(p.routeManager, p.routeOwner, internalIP, hostDevice, fromIngressProxy, fromEgressProxy, mtu); err != nil {
				return err
			}
		} else {
			if err := removeFromProxyRulesIPv4(); err != nil {
				return err
			}
		}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Ensure the agent has finished device initialization/watch synchronization before calling ReinstallRoutingRules (wait for the devices collection to sync).
2. Verify 'lo' exists on the host (`ip link show lo`) and that Cilium runs with enough privileges (NET_ADMIN) to observe devices.
3. Check that no custom device-selection option filters loopback out of the devices table.
4. Retry Reinitialize after the devices table populates; this is typically transient during startup.

Example fix

// before
lo, _, loFound := p.devices.Get(rxn, tables.DeviceByName("lo"))
if !loFound { return fmt.Errorf("failed to get loopback device") }
// after
// wait for device synchronization first, then re-run
if err := p.waitForDevicesSync(ctx); err != nil { return err }
rxn := p.db.ReadTxn()
lo, _, loFound := p.devices.Get(rxn, tables.DeviceByName("lo"))
if !loFound { return fmt.Errorf("failed to get loopback device") }

rxn := p.db.ReadTxn()
if _, _, ok := p.devices.Get(rxn, tables.DeviceByName("lo")); !ok {
    return fmt.Errorf("loopback device not yet registered; deferring reinstall")
}

func loopbackDeviceReady(devs deviceCache) bool {
    _, _, ok := devs.Get(devs.ReadTxn(), tables.DeviceByName("lo"))
    return ok
}

if err := p.ReinstallRoutingRules(ctx, mtu, ipsec, wg); err != nil {
    if strings.Contains(err.Error(), "failed to get loopback device") {
        // transient: schedule retry after device sync
        return retry.NewError(ctx, true, err)
    }
    return err
}

When it happens

Trigger: Calling Reinitialize/ReinstallRoutingRules with option.Config.EnableIPv4=true and the proxy enabled while p.devices contains no entry named 'lo' (DeviceByName("lo") lookup misses). This happens during early startup before the device watcher has synced, or if the device table was populated with a restricted device list that excludes loopback.

Common situations: Cilium agent starting on a node before netlink device discovery completes; running in environments/containers where 'lo' is missing or renamed; misconfigured --install-no-rules or custom device configuration excluding loopback; DB watchtxn race during agent restart.

Related errors

• failed to delete all direct routes: %w
• failed to get host device %s
• unable to lookup route for node %s: %w
• no route found to destination %s
• route to destination %s contains gateway %s, must be directl

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