How to fix Azure File CSI driver error in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 147 views

Azure Files CSI driver errors prevent mounting file shares in AKS clusters. Common causes include driver registration failures, storage account access issues, FIPS node pool incompatibilities, and network connectivity problems. Fixes range from checking driver installation to configuring proper network access and role-based access control.

Quick fix

Fixes Azure File CSI driver error

kubectl get pods -n kube-system | grep azure-file-csi
  1. Verify the Azure Files CSI driver is installed
  2. Check CSI driver logs for registration errors
  3. Validate storage account credentials in the secret
  4. Ensure Network Security Group allows SMB traffic
kubernetes — error
kubectl get pods -n kube-system | grep azure-file-csi
Azure File CSI driver error

What this error means

The Azure Files Container Storage Interface (CSI) driver is a storage provisioning mechanism in AKS that manages the lifecycle of Azure file shares. CSI driver errors occur when the driver fails to initialize, register with kubelet, or mount SMB file shares to pods. These errors typically manifest as "MountVolume.SetUp failed" or "driver not found" messages during pod scheduling. The driver is critical for applications that need shared persistent storage across multiple pods in your AKS cluster.

Typical symptoms

  • Pods remain in "Pending" state when using Azure file persistent volumes
  • Error message: "MountVolume.SetUp failed for volume: kubernetes.io/csi: mounter.SetUpAt failed to get CSI client: driver name file.csi.azure.com not found"
  • Error message: "failed to get account name from CSI" or permission denied errors during mount
  • Node logs show SMB connection timeouts or authentication failures
  • Storage provisioning requests fail with RBAC authorization errors
  • Mounting works on standard node pools but fails on FIPS-enabled nodes
  • Private endpoint configured storage accounts cannot be mounted dynamically

Common causes

  1. Azure Files CSI driver not installed or not properly initialized on the node
  2. Storage account credentials in Kubernetes secret do not match current storage account keys
  3. Network Security Group (NSG) rules block SMB traffic on port 445 between AKS cluster and storage account
  4. Kubelet identity lacks "Storage File Data SMB MI Admin" role on the storage account
  5. FIPS-enabled node pool used without fallback to NFS protocol (SMB not supported)
  6. Storage account network restrictions exclude the AKS cluster VNET and subnet
  7. Private endpoint configuration without proper DNS resolution or driver support
  8. Storage account key rotated at Azure level but Kubernetes secret not updated

How to fix "Azure File CSI driver error"

1Verify the Azure Files CSI driver is installed

Check if the driver is running on your nodes. Connect to your AKS cluster and list the CSI driver pods:

bash
kubectl get pods -n kube-system | grep azure-file-csi

You should see pods like azure-file-csi-driver-xxxxx running. If none appear, the driver is not installed. Install it using:

bash
az aks update --resource-group YOUR_RESOURCE_GROUP --name YOUR_CLUSTER --enable-file-csi-driver

Wait for the deployment to complete (usually 5-10 minutes).

2Check CSI driver logs for registration errors

Examine driver logs to identify specific failure reasons:

bash
kubectl logs -n kube-system -l app=azure-file-csi-driver --tail=50

Look for errors related to driver registration, kubelet communication, or initialization. Common error patterns include socket connection failures or resource conflicts. If logs show persistent errors, restart the driver pods:

bash
kubectl rollout restart daemonset azure-file-csi-driver -n kube-system
3Validate storage account credentials in the secret

Retrieve the secret containing your storage account credentials and verify it matches the current storage account:

bash
kubectl get secret azure-storage-secret -n YOUR_NAMESPACE -o jsonpath='{.data.azurestorageaccountname}' | base64 --decode
kubectl get secret azure-storage-secret -n YOUR_NAMESPACE -o jsonpath='{.data.azurestorageaccountkey}' | base64 --decode

Compare these values with your actual Azure storage account name and access key. If they do not match, update the secret:

bash
kubectl create secret generic azure-storage-secret --from-literal=azurestorageaccountname=YOUR_ACCOUNT --from-literal=azurestorageaccountkey=YOUR_KEY --dry-run=client -o yaml | kubectl apply -f -

Then delete the pod using the secret to trigger a remount with updated credentials.

4Ensure Network Security Group allows SMB traffic

Azure Files uses SMB protocol on port 445. Verify your NSG rules allow this traffic:

bash
az network nsg rule list --resource-group YOUR_RESOURCE_GROUP --nsg-name YOUR_NSG --query "[?destinationPortRange=='445'].{Direction:direction,Access:access,Priority:priority}"

If no rule allows inbound on port 445, add one:

bash
az network nsg rule create --resource-group YOUR_RESOURCE_GROUP --nsg-name YOUR_NSG --name AllowSMB --priority 100 --source-address-prefixes VirtualNetwork --destination-address-prefixes StorageAccount --destination-port-ranges 445 --protocol Tcp --access Allow --direction Inbound

Alternatively, in the Azure portal, navigate to NSG rules and add an inbound rule for port 445 from your AKS subnet.

5Assign proper role-based access control (RBAC)

For managed identity support, ensure the Kubelet identity has the necessary storage role. First, identify your cluster's kubelet identity:

bash
az aks show --resource-group YOUR_RESOURCE_GROUP --name YOUR_CLUSTER --query identity.userAssignedIdentities

Then assign the "Storage File Data SMB Share Contributor" role:

bash
az role assignment create --role "Storage File Data SMB Share Contributor" --assignee-object-id KUBELET_IDENTITY_PRINCIPAL_ID --scope /subscriptions/SUBSCRIPTION_ID/resourceGroups/STORAGE_RESOURCE_GROUP/providers/Microsoft.Storage/storageAccounts/YOUR_STORAGE_ACCOUNT

Wait 5-10 minutes for role assignment propagation before attempting to mount again.

6For FIPS-enabled nodes, use NFS instead of SMB

FIPS-enabled node pools disable certain authentication modules that SMB requires. If you are using FIPS nodes, create a custom StorageClass that uses NFS instead:

yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: azure-file-nfs
provisioner: file.csi.azure.com
parameters:
  protocol: nfs
allowVolumeExpansion: true

Apply this StorageClass and use it in your PersistentVolumeClaim:

yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-file-claim
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: azure-file-nfs
  resources:
    requests:
      storage: 100Gi

NFS provides better compatibility with FIPS while maintaining file-level sharing.

7Test the mount with a debug pod

Deploy a test pod to verify the mount works end-to-end:

yaml
apiVersion: v1
kind: Pod
metadata:
  name: debug-mount
spec:
  containers:
  - name: debug
    image: busybox:latest
    command:
      - sleep
      - "3600"
    volumeMounts:
    - name: azure-file
      mountPath: /mnt/test
  volumes:
  - name: azure-file
    persistentVolumeClaim:
      claimName: my-file-claim

Apply and check:

bash
kubectl apply -f debug-mount.yaml
kubectl wait --for=condition=Ready pod/debug-mount --timeout=300s
kubectl exec -it debug-mount -- ls -la /mnt/test

If the pod enters Running state and you can list files, the mount is working. If still pending, describe the pod to see mount errors:

bash
kubectl describe pod debug-mount

Advanced notes

For private endpoint configurations: The Azure File CSI driver cannot dynamically allocate volumes in storage accounts that only support private endpoint access. Use a separate public-accessible storage account or manually create the file share and reference it via a static PV. For CI/CD pipelines, store storage account credentials in Azure Key Vault and use Workload Identity for automatic credential injection instead of static Kubernetes secrets. On Linux nodes, verify SMB client packages are installed (cifs-utils); on Windows nodes, ensure WinRM is properly configured. For troubleshooting timeouts, run nslookup storage-account.file.core.windows.net and nc -zv storage-account.file.core.windows.net 445 from a node pod to verify DNS resolution and network connectivity before investigating driver-level issues.

Frequently asked questions

What does "Azure File CSI driver error" mean?
The Azure Files Container Storage Interface (CSI) driver is a storage provisioning mechanism in AKS that manages the lifecycle of Azure file shares. CSI driver errors occur when the driver fails to initialize, register with kubelet, or mount SMB file shares to pods. SetUp failed" or "driver not found" messages during pod scheduling.
How do I fix "Azure File CSI driver error"?
Azure Files CSI driver errors prevent mounting file shares in AKS clusters. Common causes include driver registration failures, storage account access issues, FIPS node pool incompatibilities, and network connectivity problems. Fixes range from checking driver installation to configuring proper network access and role-based access control.
What causes "Azure File CSI driver error"?
Azure Files CSI driver not installed or not properly initialized on the node Storage account credentials in Kubernetes secret do not match current storage account keys Network Security Group (NSG) rules block SMB traffic on port 445 between AKS cluster and storage account
Is the "Azure File CSI driver error" 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