{"record":{"id":"34ac009512963325","repo":"cilium/cilium","slug":"unable-to-connect-to-cilium-agent-w","errorCode":null,"errorMessage":"unable to connect to Cilium agent: %w","messagePattern":"unable to connect to Cilium agent: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"plugins/cilium-cni/cmd/cmd.go","lineNumber":590,"sourceCode":"\t\tlogfields.NetConf, n,\n\t)\n\n\tif n.PrevResult != nil {\n\t\tscopedLogger.Debug(\n\t\t\t\"CNI Previous result\",\n\t\t\tlogfields.Previous, n.PrevResult,\n\t\t)\n\t}\n\n\tcniArgs := &types.ArgsSpec{}\n\tif err = cniTypes.LoadArgs(args.Args, cniArgs); err != nil {\n\t\treturn fmt.Errorf(\"unable to extract CNI arguments: %w\", err)\n\t}\n\tscopedLogger = buildLogAttrsWithCNIArgs(scopedLogger, cniArgs)\n\n\tc, err := client.NewDefaultClientWithTimeout(defaults.ClientConnectTimeout)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"unable to connect to Cilium agent: %w\", client.Hint(err))\n\t}\n\n\tconf, err := getConfigFromCiliumAgent(c)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tfor _, hook := range cmd.onConfigReady {\n\t\tif err := hook.OnConfigReady(args, cniArgs, conf); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\t// If CNI ADD gives us a PrevResult, we're a chained plugin and *must* detect a\n\t// valid chained mode. If no chained mode we understand is specified, error out.\n\t// Otherwise, continue with normal plugin execution.\n\tif len(n.NetConf.RawPrevResult) != 0 {\n\t\tif chainAction, err := getChainedAction(n, scopedLogger); chainAction != nil {","sourceCodeStart":572,"sourceCodeEnd":608,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/plugins/cilium-cni/cmd/cmd.go#L572-L608","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the Cilium agent is running and healthy: kubectl -n kube-system get pods -l k8s-app=cilium and cilium status.","Follow the hint appended by client.Hint(err) in the wrapped message.","Verify the agent endpoint configured for the plugin (host:port / socket path) matches the agent's API settings.","Retry pod scheduling after the agent becomes ready; the failure is often transient during startup.","Check for NetworkPolicy/firewall rules blocking the agent API port on the node."],"exampleFix":"// before (CNI conf pointing at wrong agent port)\n\"cilium-agent\": \"127.0.0.1:10001\"\n// after\n\"cilium-agent\": \"127.0.0.1:8181\"","handlingStrategy":"retry","validationCode":"// Check agent reachability before ADD\nconn, err := net.DialTimeout(\"tcp\", agentAddr, 2*time.Second)\nif err != nil { return fmt.Errorf(\"cilium agent unreachable at %s\", agentAddr) }\nconn.Close()","typeGuard":null,"tryCatchPattern":"err := plugin.Add(args)\nif err != nil && strings.Contains(err.Error(), \"unable to connect to Cilium agent\") {\n  // exponential backoff retry; agent may be starting up\n  time.Sleep(backoff)\n  return plugin.Add(args)\n}","preventionTips":["Pin Cilium DaemonSet readiness before marking the node schedulable","Monitor cilium-agent health endpoints on every node","Keep agent API host/port defaults consistent between CNI conf and agent flags","Alert on agent crash loops so pod scheduling is paused"],"tags":["network","cilium-agent","connection","timeout"],"backgroundTag":"connection-refused","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}