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

Docker relies on the host system's NFS client to mount NFS volumes. Install the NFS client utilities if they're missing:

On Debian/Ubuntu:

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

On RHEL/CentOS/Fedora:

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

On Alpine (common in CI environments):

apk add nfs-utils

Verify the installation:

showmount --version

Before debugging Docker, verify that NFS works at the host level:

# 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

If the manual mount fails, the issue is with NFS configuration, not Docker. Common errors and their meanings:
- "Connection refused": NFS server not running or blocked by firewall
- "No route to host": Network connectivity issue
- "Access denied": Export rules don't permit this host

Ensure the required ports are open between Docker host and NFS server:

Required NFS ports:
- TCP/UDP 2049 (NFS)
- TCP/UDP 111 (portmapper/rpcbind)

Test connectivity:

# 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>

On the NFS server (if you have access):

# 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

Check that the NFS server is exporting the correct path with appropriate permissions:

On the NFS server, check /etc/exports:

cat /etc/exports

The export entry should include your Docker host's IP or subnet:

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

Key options to check:
- rw or ro: Read-write or read-only access
- no_root_squash: Allows root access (needed for some Docker operations)
- no_subtree_check: Improves reliability

After modifying /etc/exports, reload:

sudo exportfs -ra

Ensure your Docker NFS volume is configured correctly:

Using docker volume create:

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

In docker-compose.yml:

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"

Common mistakes:
- Missing colon before the path in device (should be :/path not /path)
- Using hostname instead of IP (can cause DNS resolution issues)
- Incorrect NFS version (try nfsvers=3 or nfsvers=4)

Add mount options to work around common NFS problems:

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"

Useful mount options:
- soft: Return an error if server is unreachable (instead of hanging indefinitely)
- timeo=180: Timeout in deciseconds (180 = 18 seconds)
- nolock: Disable file locking (helps with some NFS server configurations)
- nfsvers=3 or nfsvers=4: Force specific NFS version
- tcp: Force TCP protocol (more reliable than UDP)

For Docker for Windows connecting to Linux NFS server:
Add the hard and nolock options, and ensure the NFS server has insecure in the export options.

NFS servers often use "root squash" which maps root access to nobody/nogroup, causing permission issues for Docker:

Symptoms:
- "Permission denied" errors when Docker tries to initialize volume
- Container can read but not write to NFS mount

Option 1: Add no_root_squash to NFS export (security implications):

# 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

Option 2: Use nocopy option in Docker:

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

This prevents Docker from trying to copy files to the volume, avoiding permission issues during initialization.

Option 3: Ensure world-readable permissions:
On the NFS server, ensure the directory has appropriate permissions:

chmod 755 /path/to/share

Stale NFS handles or cached Docker volumes can cause persistent mount failures:

Clear stale Docker volumes:

# 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

Clear stale NFS mounts on host:

# 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

Restart Docker daemon:

sudo systemctl restart docker

Docker Desktop runs containers inside a VM, which has limited NFS support:

Docker Desktop for Mac:
- Recent versions have NFS client support, but it may require additional configuration
- If NFS mounts fail, check Docker Desktop settings for virtualization framework options
- Some users report success switching between "Apple Virtualization" and "QEMU"

Docker Desktop for Windows:
- WSL2 backend may have better NFS support than Hyper-V
- Ensure NFS server has insecure option in exports (for non-privileged ports)

Alternative approach - mount on host first:

# 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

This bypasses Docker's NFS volume driver and uses a simple bind mount instead.