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

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 197 views

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.

Quick fix

Fixes driver name [driver-name] not found in the list of registered CSI drivers

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

Check which nodes have the CSI driver registered
Verify the CSI driver pods are running
Investigate failing or missing driver pods
Check node taints and nodeSelector constraints

kubernetes — error

$kubectl get csinodes
kubectl get csidriver
kubectl describe csinode <node-name>
driver name [driver-name] not found in the list of registered CSI drivers

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.

Typical symptoms

Pod remains in Pending state when attempting to mount PersistentVolumes
Error shows "driver name [driver-name] not found in the list of registered CSI drivers"
Pod logs show "MountVolume.SetUp failed... CSI client driver not found"
New PersistentVolumeClaims fail to provision with ProvisioningFailed status
Volumes fail to attach even though storage backend is accessible and online
Some nodes can mount volumes successfully while others consistently fail

Common causes

CSI driver Helm chart or DaemonSet not deployed to the cluster
CSI driver pods failed to start: CrashLoopBackOff, ImagePullBackOff, or other initialization errors
Node taints (e.g., NoSchedule, NoExecute) preventing CSI driver DaemonSet from deploying to certain nodes
CSI Node DaemonSet has restrictive nodeSelector that doesn't match all worker nodes
Kubelet plugin registration failed due to socket permission issues or driver misconfiguration
CSI driver pod crashlooping due to invalid configuration, missing credentials, or incompatible Kubernetes version
Disk space exhausted on worker nodes preventing CSI driver pod startup
Network connectivity issue preventing CSI driver from communicating with storage backend (API/controller)
IAM/RBAC permissions insufficient for cloud-native CSI drivers (EBS, Azure Disk, GCP PD)

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.

Advanced notes

CSI drivers require kubelet plugin registration mechanism to work correctly. Ensure kubelet is running with --allow-privileged=true and has access to /var/lib/kubelet/plugins/ directory. Each CSI driver implementation has specific requirements: EBS needs IAM permissions, Azure Disk needs Azure credentials, GCP PD needs Workload Identity, Secrets Store CSI needs SecretProviderClass definitions. For multi-cloud clusters, deploy multiple CSI drivers; they coexist by having unique driver names (e.g., ebs.csi.aws.com vs azure.csi.io). Kubernetes 1.13+ is required for CSI support; older clusters must upgrade. Some CSI drivers support topology-aware provisioning; configure allowedTopologies in StorageClass to ensure volumes provision in correct zones. For production, ensure CSI driver controller pods have sufficient resources and are spread across nodes for HA. Storage class selection matters: test different parameters (IOPS, volume type) and use fsGroupChangePolicy in Kubernetes 1.20+ for large volumes.

Frequently asked questions

What does "driver name [driver-name] not found in the list of registered CSI driv" mean?: CSI drivers are plugins that run as DaemonSets on Kubernetes worker nodes. ). When a pod tries to use a volume with a CSI driver that isn't registered on its node, Kubernetes cannot complete the mount.
How do I fix "driver name [driver-name] not found in the list of registered CSI driv"?: 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 causes "driver name [driver-name] not found in the list of registered CSI driv"?: CSI driver Helm chart or DaemonSet not deployed to the cluster CSI driver pods failed to start: CrashLoopBackOff, ImagePullBackOff, or other initialization errors Node taints (e.g., NoSchedule, NoExecute) preventing CSI driver DaemonSet from deploying to certain nodes
Is the "driver name [driver-name] not found in the list of registered CSI driv" error serious?: Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading

📚Kubernetes Official Documentation
🔗
kubernetes-csi.github.io: troubleshooting
🔗
kubernetes-csi.github.io: csi driver object
🔗
kubernetes-csi.github.io: deploying
🔗
secrets-store-csi-driver.sigs.k8s.io: troubleshooting
📖
Google Cloud Docs: install csi driver(Official Docs)

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

Quick fix

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

Frequently asked questions

Related errors

Official resources & further reading