How to fix Error response from daemon: error while mounting volume: NFS mount failed in Docker

What this error means

When Docker attempts to mount an NFS (Network File System) volume into a container, it relies on the host system's NFS client to establish the connection to the remote NFS server. The "NFS mount failed" error indicates that this connection could not be established. NFS volumes in Docker are useful for sharing persistent data across multiple containers or hosts, particularly in clustered environments like Docker Swarm. However, unlike local bind mounts, NFS mounts require proper network configuration, server accessibility, and compatible mount options. The error can originate from various points in the NFS mounting chain: the Docker daemon failing to initiate the mount, the NFS client being unavailable or misconfigured, network issues preventing communication with the NFS server, or the NFS server rejecting the mount request due to export rules or permissions.

Typical symptoms

• Container fails to start with 'error while mounting volume: NFS mount failed'
• Docker Compose services hang during volume mounting phase
• Error message includes 'mount.nfs: rpc.statd is not running' or similar RPC errors
• Kubernetes pods fail with 'MountVolume.SetUp failed' for NFS persistent volumes
• NFS mounts work directly on the host but fail inside Docker
• Docker service or stack deployments fail at the volume mounting step
• Connection refused or timeout errors when attempting NFS volume mounts

Common causes

1. NFS client utilities are not installed on the Docker host
2. NFS server is unreachable due to network issues or firewall rules
3. Incorrect NFS server address or export path in volume configuration
4. NFS server export permissions do not allow the Docker host
5. Missing or incorrect NFS version specification in mount options
6. The exported NFS directory does not exist on the server
7. Root squash settings on NFS server prevent Docker from accessing files
8. Stale file handles from previous mount attempts
9. Docker Desktop VM lacks NFS client support (macOS/Windows)
10. Firewall blocking NFS ports (2049, 111 for portmapper)

How to fix "Error response from daemon: error while mounting volume: NFS mount failed"

sudo apt-get update
sudo apt-get install nfs-common

sudo yum install nfs-utils
# or on newer systems:
sudo dnf install nfs-utils

apk add nfs-utils

showmount --version

# List exports available from the NFS server
showmount -e <nfs-server-ip>

# Test manual mount
sudo mkdir -p /tmp/nfs-test
sudo mount -t nfs <nfs-server-ip>:/path/to/export /tmp/nfs-test

# Check if mount succeeded
df -h /tmp/nfs-test

# Clean up test mount
sudo umount /tmp/nfs-test

# Check if NFS port is accessible
nc -zv <nfs-server-ip> 2049

# Check portmapper
nc -zv <nfs-server-ip> 111

# Test with rpcinfo
rpcinfo -p <nfs-server-ip>

# Check if NFS services are running
systemctl status nfs-server
systemctl status rpcbind

# Open firewall ports (firewalld)
sudo firewall-cmd --permanent --add-service=nfs
sudo firewall-cmd --permanent --add-service=mountd
sudo firewall-cmd --permanent --add-service=rpc-bind
sudo firewall-cmd --reload

cat /etc/exports

/path/to/share 192.168.1.0/24(rw,sync,no_subtree_check)

sudo exportfs -ra

docker volume create --driver local \
  --opt type=nfs \
  --opt o=addr=192.168.1.100,nfsvers=4,rw \
  --opt device=:/path/to/export \
  my-nfs-volume

version: '3.8'
services:
  app:
    image: myapp
    volumes:
      - nfs-data:/app/data

volumes:
  nfs-data:
    driver: local
    driver_opts:
      type: nfs
      o: "addr=192.168.1.100,nfsvers=4,rw,soft,nolock"
      device: ":/path/to/export"

volumes:
  nfs-data:
    driver: local
    driver_opts:
      type: nfs
      o: "addr=192.168.1.100,nfsvers=4,rw,soft,timeo=180,nolock"
      device: ":/path/to/export"

# On NFS server, edit /etc/exports:
/path/to/share 192.168.1.0/24(rw,sync,no_root_squash,no_subtree_check)

sudo exportfs -ra

docker run -v nfs-volume:/app/data:nocopy myimage

chmod 755 /path/to/share

# List all volumes
docker volume ls

# Remove the problematic volume (if not in use)
docker volume rm my-nfs-volume

# Recreate the volume
docker volume create --driver local \
  --opt type=nfs \
  --opt o=addr=192.168.1.100,nfsvers=4 \
  --opt device=:/path/to/export \
  my-nfs-volume

# Check for stale mounts
mount | grep nfs

# Force unmount stale entries
sudo umount -f /var/lib/docker/volumes/my-nfs-volume/_data

# If that fails, lazy unmount
sudo umount -l /var/lib/docker/volumes/my-nfs-volume/_data

sudo systemctl restart docker

# Mount NFS to host directory
sudo mount -t nfs 192.168.1.100:/export /mnt/nfs-share

# Use bind mount in Docker
docker run -v /mnt/nfs-share:/app/data myimage

Advanced notes

# On the NFS client (Docker host)
rpcdebug -m nfs -s all
dmesg | tail -50

# After debugging, disable verbose logging
rpcdebug -m nfs -c all

o: "addr=192.168.1.100,nfsvers=4,rsize=65536,wsize=65536,hard,timeo=600"

Frequently asked questions

What does "Error response from daemon: error while mounting volume: NFS mount fai" mean?

When Docker attempts to mount an NFS (Network File System) volume into a container, it relies on the host system's NFS client to establish the connection to the remote NFS server. The "NFS mount failed" error indicates that this connection could not be established. NFS volumes in Docker are useful for sharing persistent data across multiple containers or hosts, particularly in clustered environments like Docker Swarm.

How do I fix "Error response from daemon: error while mounting volume: NFS mount fai"?

This error occurs when Docker cannot mount an NFS volume to a container. Common causes include incorrect NFS server configuration, missing NFS client utilities, network connectivity issues, or permission problems.

What causes "Error response from daemon: error while mounting volume: NFS mount fai"?

NFS client utilities are not installed on the Docker host NFS server is unreachable due to network issues or firewall rules Incorrect NFS server address or export path in volume configuration

Is the "Error response from daemon: error while mounting volume: NFS mount fai" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• no basic auth credentials

  How to fix 'no basic auth credentials' in Docker

  LOW

• dial tcp: connect: network is unreachable

  How to fix 'network is unreachable' in Docker

  MEDIUM

• failed to solve: failed to compute cache key: failed to calculate checksum: no build stage in current context

  How to fix 'no build stage in current context' in Docker

  MEDIUM

• net/http: request canceled while waiting for connection

  How to fix 'request canceled while waiting for connection' in Docker

  MEDIUM

• WSL 2 requires an update to its kernel component

  How to fix 'WSL 2 requires an update to its kernel component' in Docker

  MEDIUM

• dial tcp: i/o timeout

  How to fix 'dial tcp: i/o timeout' in Docker

  MEDIUM

Official resources & further reading

• 📚Docker Official Documentation
• 📖
  Volumes - Docker Docs(Official Docs)
• 📖
  Troubleshooting the Docker daemon - Docker Docs(Official Docs)
• 📖
  docker volume create - Docker Docs(Official Docs)
• 💬
  NFS Share Volume wont mount to Docker container - Stack Overflow(Stack Overflow)
• 💬
  Docker refuses to mount NFS share - Stack Overflow(Stack Overflow)
• 💬
  Docker nfs volume - no such file or directory - Stack Overflow(Stack Overflow)
• 💬
  Docker for Windows unable to mount nfs drive with docker-compose - Stack Overflow(Stack Overflow)
• 🐙
  NFS Kubernetes Volume mount in Docker 2.4.0.0 - GitHub Issue #4958(GitHub)
• 🐙
  [BUG] mount nfs volume in docker-compose.yml issue - GitHub Issue #12308(GitHub)
• 🐙
  M1 Docker Desktop: Unable to mount NFS volumes - GitHub Issue #5534(GitHub)