How to troubleshoot NFS stale file handle errors

An NFS stale file handle error appears when a client still has a server-issued reference for a file, directory, or export root that no longer matches the object on the server. The mount can remain visible while stat, ls, backups, or application file opens fail with Stale file handle.

Most incidents start after a server-side path replacement, export reload, storage failover, filesystem remount, or maintenance job that changed the object behind an export. The recovery path is to confirm the client failure, verify the server is exporting the intended path, refresh the export state, and make the client mount request new handles.

Start with a normal unmount and only escalate when the mount is unreachable or the ordinary unmount cannot return. Forced and lazy unmounts can leave application references in an uncertain state, so stop the workload using the mount when possible and keep lazy unmount for shutdown or last-resort recovery.

Steps to troubleshoot NFS stale file handle errors:

Reproduce the stale handle from the client path.
```
$ stat /mnt/projects
stat: cannot statx '/mnt/projects': Stale file handle
```
Use the path that first failed in the application or shell. If the error is permission denied, connection timed out, or no route to host, troubleshoot that separate condition before remounting.
Related: How to troubleshoot NFS permission denied errors

Identify the mounted NFS source for that client path.

$ findmnt --kernel --types nfs,nfs4 --target /mnt/projects --output TARGET,SOURCE,FSTYPE,OPTIONS
TARGET        SOURCE                              FSTYPE OPTIONS
/mnt/projects files.example.net:/srv/nfs/projects nfs4   rw,relatime,vers=4.2,rsize=1048576,wsize=1048576,hard,proto=tcp,timeo=600,retrans=2,sec=sys

Keep the server name, exported path, local mount point, and NFS version together. The remount must use the intended export, not a guessed replacement path.
Related: How to check the NFS version for a mounted export

Confirm on the server that the export root is backed by the expected filesystem.
```
$ findmnt /srv/nfs/projects
TARGET            SOURCE    FSTYPE OPTIONS
/srv/nfs/projects /dev/sdb1 xfs    rw,relatime
```
If the export root was deleted, recreated as an empty directory, or lost its backing mount, restore that server-side path before remounting clients.
Check the active server export table.
```
$ sudo exportfs -v
/srv/nfs/projects
        192.0.2.0/24(sync,wdelay,hide,no_subtree_check,sec=sys,rw,root_squash,no_all_squash)
```
The active table should show the same export path and client range used by the failed mount. If the saved export changed but this output did not, refresh the exports before touching the client.
Related: How to list NFS exports on a server
Re-export the server paths after fixing /etc/exports, export drop-ins, or the backing mount.
```
$ sudo exportfs -r
```
No output usually means exportfs synchronized the active export table with /etc/exports and /etc/exports.d/. If exportfs reports that the path does not support NFS export, fix the backing filesystem or export root first.
Related: How to reload NFS exports
Flush the server export cache only when stale handles persist after the path and active export table are correct.
```
$ sudo exportfs -f
```
exportfs -f flushes the kernel export table for all exports on the server. Use it during a maintenance window or after checking client impact on busy shared servers.
List local processes that still hold the client mount.
```
$ sudo fuser --verbose --mount /mnt/projects
                     USER        PID ACCESS COMMAND
/mnt/projects:       appuser    4186 ..c..  backupd
                     root      4201 F....  rsync
```
Stop or restart the listed application through its normal service control path before unmounting when possible. A shell whose current directory is under the mount can also keep the target busy.
Unmount the stale client mount normally.
```
$ sudo umount /mnt/projects
```
No output usually means the mount detached cleanly. If the command reports target is busy, repeat the fuser check and close the remaining holders before forcing the unmount.
Related: How to clean up a stale NFS client mount
Force the unmount only when the server is unreachable or the normal unmount cannot return.
```
$ sudo umount --force --no-canonicalize /mnt/projects
```
Use the exact absolute mount path, not a symlink or a path inside the stale filesystem. Avoid umount –lazy unless detaching the mount is the last way to recover shutdown or shell control, because a lazy unmount can keep old references alive until processes release them.
Mount the export again from the client.
```
$ sudo mount -t nfs files.example.net:/srv/nfs/projects /mnt/projects
```
If /etc/fstab, systemd, or an automounter manages the mount, use the matching site command such as sudo mount /mnt/projects or restart the automount map instead of creating a second manual mount.
Related: How to mount an NFS export on Linux
Related: How to automount an NFS export with autofs
Retest the original client path.
```
$ stat /mnt/projects
  File: /mnt/projects
  Size: 4096        Blocks: 8          IO Block: 1048576 directory
Device: 0,54    Inode: 128         Links: 3
Access: (0755/drwxr-xr-x)  Uid: ( 1000/    user)   Gid: ( 1000/    user)
##### snipped #####
```
The stale handle is cleared when the same path that failed returns metadata or the application opens its files again. If the error returns immediately, keep the client unmounted and inspect the server-side storage, export root, failover process, or application that replaces files behind the export.

Author: Mohd Shakir Zakaria
Mohd Shakir Zakaria is a cloud architect with deep roots in software development and open-source advocacy. Certified in AWS, Red Hat, VMware, ITIL, and Linux, he specializes in designing and managing robust cloud and on-premises infrastructures.