How to fix driver name [driver-name] not found in the list of registered CSI drivers in Kubernetes

KubernetesINTERMEDIATEHIGH

A CSI (Container Storage Interface) driver required for volume provisioning or mounting is not available on worker nodes. This occurs when the driver DaemonSet isn't deployed, pods failed to start, or node taints prevent scheduling. Fix by deploying the driver via Helm, checking node scheduling constraints, and verifying driver registration.

What this error means

CSI drivers are plugins that run as DaemonSets on Kubernetes worker nodes. They enable dynamic volume provisioning and mounting for various storage backends (AWS EBS, Azure Disk, NFS, etc.). When a pod tries to use a volume with a CSI driver that isn't registered on its node, Kubernetes cannot complete the mount. This registration happens automatically via the kubelet plugin registration mechanism when CSI driver pods start successfully. If the driver pods aren't running or can't register (due to taints, resource constraints, or startup failures), volumes relying on that driver become unavailable.

How to fix "driver name [driver-name] not found in the list of registered CSI drivers"

1Check which nodes have the CSI driver registered

List all CSI drivers and nodes:

bash

kubectl get csinodes
kubectl get csidriver
kubectl describe csinode <node-name>

If the CSINode object shows no drivers, or the driver you need is missing, the driver isn't registered on that node.

2Verify the CSI driver pods are running

Check deployment status of the driver:

bash

# Find CSI driver namespace (often kube-system, default, or custom)
kubectl get pods -A | grep -i csi

# Check specific driver pods
kubectl get pods -n <driver-namespace> -l app=<driver-name>
kubectl get pods -n <driver-namespace> -o wide | grep <driver-name>

Expected: Node pods running on each worker node, Controller pod in at least one replica. If pods are CrashLoopBackOff or Pending, move to step 3.

3Investigate failing or missing driver pods

If pods aren't running, check logs:

bash

kubectl logs -n <driver-namespace> <csi-node-pod> -c <node-container>
kubectl describe pod -n <driver-namespace> <csi-node-pod>

Common errors:
- ImagePullBackOff: Driver image not accessible; verify image registry and credentials
- CrashLoopBackOff: Driver startup failure; check logs for configuration/permission issues
- Pending: Pod scheduling blocked; check node taints and nodeSelector (next step)

For permission issues, ensure kubelet can access /var/lib/kubelet/plugins/ directory.

4Check node taints and nodeSelector constraints

Node taints may prevent DaemonSet from scheduling:

bash

kubectl describe node <node-name> | grep Taints
kubectl get daemonset -n <driver-namespace> <driver-name> -o yaml | grep -A5 tolerations
kubectl get daemonset -n <driver-namespace> <driver-name> -o yaml | grep -A5 nodeSelector

If the DaemonSet lacks tolerations for node taints, add them:

yaml

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: csi-node
spec:
  template:
    spec:
      tolerations:
      - key: node-role.kubernetes.io/master
        operator: Exists
      - key: node-role.kubernetes.io/control-plane
        operator: Exists
      - key: <custom-taint-key>
        operator: Equal
        value: <custom-taint-value>
      nodeSelector:
        kubernetes.io/os: linux  # Ensure it matches your nodes

5Deploy the CSI driver if not already installed

Install via Helm (most drivers provide official Helm charts):

AWS EBS CSI Driver:

bash

helm repo add aws-ebs-csi-driver https://kubernetes-sigs.github.io/aws-ebs-csi-driver
helm install aws-ebs-csi-driver aws-ebs-csi-driver/aws-ebs-csi-driver \
  -n kube-system \
  --set serviceAccount.controller.annotations."eks.amazonaws.com/role-arn"=arn:aws:iam::ACCOUNT_ID:role/AmazonEKS_EBS_CSI_DriverRole

Azure Disk CSI Driver:

bash

helm repo add azuredisk-csi-driver https://raw.githubusercontent.com/kubernetes-sigs/azuredisk-csi-driver/master/charts
helm install azuredisk-csi-driver azuredisk-csi-driver/azuredisk-csi-driver \
  -n kube-system

GCP Persistent Disk CSI Driver:

bash

helm repo add pd-csi-driver https://kubernetes-sigs.github.io/gcp-compute-persistent-disk-csi-driver
helm install gcp-compute-pd-csi-driver pd-csi-driver/gcp-compute-pd-csi-driver \
  -n kube-system

NFS CSI Driver:

bash

helm repo add nfs-subdir-external-provisioner https://kubernetes-sigs.github.io/nfs-subdir-external-provisioner
helm install nfs-subdir-external-provisioner nfs-subdir-external-provisioner/nfs-subdir-external-provisioner \
  -n kube-system \
  --set nfs.server=<nfs-server-ip> \
  --set nfs.path=/exports

After installation, verify pods are running and nodes register the driver (step 2).

6Configure IAM/RBAC permissions for cloud drivers

Cloud-native drivers (EBS, Azure Disk, GCP PD) require proper credentials:

For AWS EBS:

Create IAM role with EBS permissions, then annotate the Kubernetes ServiceAccount:

yaml

apiVersion: v1
kind: ServiceAccount
metadata:
  name: ebs-csi-controller-sa
  namespace: kube-system
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::ACCOUNT:role/EBS_CSI_DriverRole

For Azure Disk:

Ensure cluster has Azure RBAC or service principal configured:

bash

az aks show -n <cluster-name> -g <rg> | grep -i "servicePrincipal"

For GCP PD:

Ensure Workload Identity is configured and ServiceAccount has proper IAM roles.

7Verify driver registration and test volume provisioning

After driver deployment:

bash

kubectl get csidriver
kubectl get csinodes -o wide
kubectl describe csinode <node-name>

Then test provisioning:

bash

kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-csi-pvc
spec:
  storageClassName: <csi-storage-class>  # e.g., ebs-gp2
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
EOF

kubectl get pvc test-csi-pvc
kubectl describe pvc test-csi-pvc

PVC should bind within seconds. If stuck in Pending, describe again to see new errors.

How to fix driver name [driver-name] not found in the list of registered CSI drivers in Kubernetes

What this error means

Typical symptoms

Common causes

How to fix "driver name [driver-name] not found in the list of registered CSI drivers"

Advanced notes

Related errors

Official resources & further reading