cilium/cilium · critical

unable to connect to Cilium agent: %w

Error message

unable to connect to Cilium agent: %w

What it means

The CNI plugin could not establish a connection to the Cilium agent's health/API endpoint within defaults.ClientConnectTimeout during Cmd.Add. The error is wrapped with client.Hint(err), which appends diagnostic hints (e.g. checking the agent is running and its host/API settings). Without the agent the plugin cannot fetch config or allocate IPs.

Source

Thrown at plugins/cilium-cni/cmd/cmd.go:590

		logfields.NetConf, n,
	)

	if n.PrevResult != nil {
		scopedLogger.Debug(
			"CNI Previous result",
			logfields.Previous, n.PrevResult,
		)
	}

	cniArgs := &types.ArgsSpec{}
	if err = cniTypes.LoadArgs(args.Args, cniArgs); err != nil {
		return fmt.Errorf("unable to extract CNI arguments: %w", err)
	}
	scopedLogger = buildLogAttrsWithCNIArgs(scopedLogger, cniArgs)

	c, err := client.NewDefaultClientWithTimeout(defaults.ClientConnectTimeout)
	if err != nil {
		return fmt.Errorf("unable to connect to Cilium agent: %w", client.Hint(err))
	}

	conf, err := getConfigFromCiliumAgent(c)
	if err != nil {
		return err
	}

	for _, hook := range cmd.onConfigReady {
		if err := hook.OnConfigReady(args, cniArgs, conf); err != nil {
			return err
		}
	}

	// If CNI ADD gives us a PrevResult, we're a chained plugin and *must* detect a
	// valid chained mode. If no chained mode we understand is specified, error out.
	// Otherwise, continue with normal plugin execution.
	if len(n.NetConf.RawPrevResult) != 0 {
		if chainAction, err := getChainedAction(n, scopedLogger); chainAction != nil {

View on GitHub (pinned to ac7b90affa)

Solutions

1. Check the Cilium agent is running and healthy: kubectl -n kube-system get pods -l k8s-app=cilium and cilium status.
2. Follow the hint appended by client.Hint(err) in the wrapped message.
3. Verify the agent endpoint configured for the plugin (host:port / socket path) matches the agent's API settings.
4. Retry pod scheduling after the agent becomes ready; the failure is often transient during startup.
5. Check for NetworkPolicy/firewall rules blocking the agent API port on the node.

Example fix

// before (CNI conf pointing at wrong agent port)
"cilium-agent": "127.0.0.1:10001"
// after
"cilium-agent": "127.0.0.1:8181"

// Check agent reachability before ADD
conn, err := net.DialTimeout("tcp", agentAddr, 2*time.Second)
if err != nil { return fmt.Errorf("cilium agent unreachable at %s", agentAddr) }
conn.Close()

err := plugin.Add(args)
if err != nil && strings.Contains(err.Error(), "unable to connect to Cilium agent") {
  // exponential backoff retry; agent may be starting up
  time.Sleep(backoff)
  return plugin.Add(args)
}

When it happens

Trigger: client.NewDefaultClientWithTimeout(defaults.ClientConnectTimeout) fails: Cilium agent not running, CILIUM_CNI_AGENT_... socket/endpoint misconfigured, agent restarting, or network policy blocking the UNIX socket/TCP endpoint.

Common situations: Agent pod not yet ready (node just bootstrapped); Cilium DaemonSet crashed; agent URL host/port wrong in the CNI config; host networking firewall blocks the agent port; upgrading Cilium while pods are being scheduled.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• failed to create cilium agent client after %f seconds timeou
• i/o timeout
• Cilium API client timeout exceeded
• device %d not found for endpoint %s: %w
• cannot forward proxied DNS lookup: %w

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