☸️ Kubernetes Error Guide: 'cni config uninitialized' Node NotReady Network Failure

Overview

When a node stays NotReady right after joining a cluster, the kubelet almost always reports this condition:

container runtime network not ready: NetworkReady=false reason:NetworkPluginNotReady
message:Network plugin returns error: cni plugin not initialized

or the closely related:

cni config uninitialized

The kubelet does not implement pod networking itself. It delegates to a CNI (Container Network Interface) plugin — Calico, Cilium, Flannel, Weave, or a cloud CNI. On startup the kubelet looks in /etc/cni/net.d/ for a valid CNI configuration and in /opt/cni/bin/ for the plugin binaries. Until it finds a usable config, it considers pod networking uninitialized, marks the node NotReady, and refuses to schedule normal pods there.

This is expected on a brand-new node before a CNI is installed. It is a genuine problem when the CNI is installed but its DaemonSet pods are failing, so the config never gets written or is invalid.

Symptoms

• kubectl get nodes shows the node as NotReady.
• kubectl describe node Ready condition reads KubeletNotReady with the cni config uninitialized message.
• Pods scheduled to the node stay ContainerCreating.
• CNI DaemonSet pods (e.g. calico-node, cilium, kube-flannel) are CrashLoopBackOff, Pending, or absent.
• /etc/cni/net.d/ is empty or contains an invalid/partial config.

Common Root Causes

1. No CNI installed yet

A fresh kubeadm-initialized cluster has no networking until you apply a CNI manifest. Every node stays NotReady until then. This is the most common case.

2. CNI DaemonSet pods failing

The CNI is applied but its pods crash (bad config, missing RBAC, wrong pod CIDR, image pull failure), so they never lay down /etc/cni/net.d/*.conflist.

3. Missing or mismatched plugin binaries

/opt/cni/bin/ lacks the required binaries, or the installed CNI version does not match the binaries present, so the config references a plugin that cannot execute.

4. Pod CIDR mismatch

The CNI’s configured pod CIDR does not match --pod-network-cidr given to kubeadm init (or the node’s podCIDR), so the plugin refuses to initialize.

5. Stale or conflicting config files

Leftover configs from a previous CNI in /etc/cni/net.d/ confuse the runtime and produce an invalid network state.

Diagnostic Workflow

Step 1: Confirm the node condition and message

kubectl get nodes
kubectl describe node <node-name> | grep -A3 "Ready"

Step 2: Check the CNI DaemonSet pods

kubectl get pods -n kube-system -o wide | grep -Ei "calico|cilium|flannel|weave"
kubectl logs -n kube-system <cni-pod> --previous

Step 3: Inspect the CNI config and binaries on the node

sudo ls -l /etc/cni/net.d/
sudo ls -l /opt/cni/bin/

Step 4: Ask the container runtime for its view

sudo crictl info | grep -A5 -i cni
sudo journalctl -u kubelet --no-pager | grep -i "cni" | tail -20

Step-by-Step Resolution

1. Install a CNI if none exists. On a fresh cluster this is the whole fix. Apply your chosen plugin, matching its pod CIDR to kubeadm init:

kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.28.0/manifests/calico.yaml

2. Wait for the DaemonSet to become Ready and confirm the config appears:

kubectl rollout status ds/calico-node -n kube-system
sudo ls -l /etc/cni/net.d/

3. If CNI pods are crashing, read their logs and fix the cause. Common issues are RBAC, wrong CALICO_IPV4POOL_CIDR/pod CIDR, or image pull failures:

kubectl logs -n kube-system <cni-pod> --previous
kubectl describe pod -n kube-system <cni-pod>

4. Verify the pod CIDR matches. The CNI’s CIDR must equal what the control plane expects:

kubectl cluster-info dump | grep -m1 cluster-cidr
kubectl get node <node-name> -o jsonpath='{.spec.podCIDR}{"\n"}'

5. Remove stale configs from a prior CNI, keeping only the active plugin’s file, then restart the kubelet:

sudo ls /etc/cni/net.d/
# remove leftover non-active configs only after confirming the active one
sudo systemctl restart kubelet

6. Confirm the node goes Ready:

kubectl get nodes -w

node-01   Ready    <none>   6m   v1.30.2

Prevention

• Install the CNI as part of cluster bootstrap automation, immediately after kubeadm init/join.
• Pin CNI manifest versions and keep the plugin’s pod CIDR in sync with --pod-network-cidr.
• Monitor the CNI DaemonSet’s rollout so a crashed agent pages you before nodes go NotReady.
• Keep /opt/cni/bin/ populated by the CNI installer; do not hand-edit /etc/cni/net.d/.
• When switching CNIs, fully remove the old plugin’s config and binaries first.

Related Errors

• failed to set up sandbox container ... plugin type="calico" failed — CNI installed but the plugin errors per-pod.
• Failed to create pod sandbox: ... network is not ready — the same root cause seen from pod creation.
• node not ready taints keeping pods Pending — a downstream effect of this condition.
• Failed to allocate address / IPAM exhaustion — a CNI that initialized but ran out of pod IPs.

Frequently Asked Questions

Why is my brand-new node NotReady with cni config uninitialized? A fresh cluster has no pod networking until you install a CNI plugin. Apply Calico, Cilium, Flannel, or your cloud CNI and the node becomes Ready once its config is written to /etc/cni/net.d/.

Where does the kubelet look for CNI config? In /etc/cni/net.d/ for the .conflist/.conf file and in /opt/cni/bin/ for the plugin binaries. If either is missing or invalid, networking stays uninitialized.

My CNI is installed but the node is still NotReady — what now? Check the CNI DaemonSet pods with kubectl logs --previous. Crashing agent pods never write the config. Fix the crash cause (RBAC, pod CIDR mismatch, image pull) and the config will appear. The DevOps AI prompt library has prompts for diagnosing CNI DaemonSet failures.

Does the pod CIDR really need to match? Yes. If the CNI’s configured CIDR differs from --pod-network-cidr/the node’s podCIDR, the plugin refuses to initialize. Align them and restart the kubelet.

Do I need to restart the kubelet after installing a CNI? Usually not — the kubelet detects the new config within seconds. Restart it only if a stale config was removed or the node does not pick up the change. For more, see the Kubernetes & Helm guides.