How to troubleshoot NFS stale file handle errors

A stale NFS file handle means the client is still using a cached server file handle for an export, directory, or file that the server no longer maps to the same object. Commands such as stat, ls, or application file opens may fail even though the network path is reachable and the mount still appears in the client mount table.

The recovery path is to prove the failure on the client, confirm that the server is still exporting the intended path, refresh the server export state when the path changed, and remount the client so it asks for new handles. Treat this separately from permission denied or timeout errors, because stale handles usually follow a server-side directory replacement, filesystem remount, export reload, storage failover, or maintenance operation.

Use a normal unmount first so active applications can close files cleanly. Forced or lazy unmounts are recovery tools for unreachable or wedged network filesystems, not a first response; stop the application using the mount when possible, and restore the server-side export root before repeatedly remounting clients.

Steps to troubleshoot NFS stale file handle errors:

Reproduce the stale handle from the client mount point.
```
$ stat /mnt/projects
stat: cannot statx '/mnt/projects': Stale file handle
```
Use the command or application path that first reported the failure. 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 NFS source mounted at that client path.
```
$ findmnt -t nfs,nfs4 /mnt/projects
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, and local mount point together. The remount step must use the same intended source, not a guessed replacement path.

Related: How to check the NFS version for a mounted export
Confirm on the server that the exported path 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, replaced by an empty directory, or lost its backing filesystem, restore that server-side path first. A client remount cannot recover handles for an object the server no longer exports.
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 export table should show the path and client range that match the failed client mount. If the saved export changed but the active table did not, refresh the exports before touching clients.

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
```
exportfs -r synchronizes the active export table with /etc/exports and /etc/exports.d/. No output usually means the refresh completed without reporting a syntax or path problem.

Related: How to reload NFS exports
Flush the server export cache only when the stale handle persists 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, especially on busy shared servers.
Unmount the stale client mount normally.
```
$ sudo umount /mnt/projects
```
If the target is busy, identify the process with sudo fuser --mount /mnt/projects, stop the application using the mount, and run the normal unmount again.
Use a forced unmount only when the server is unreachable or the normal unmount cannot return.
```
$ sudo umount -f /mnt/projects
```
Use an absolute mount path with umount -f. Avoid umount -l unless detaching the mount is the last way to recover the shell or shutdown path, because a lazy unmount can leave old references alive until processes release them and may require a reboot before a clean remount.
Mount the export again from the client.
```
$ sudo mount -t nfs files.example.net:/srv/nfs/projects /mnt/projects
```
If the mount is managed by /etc/fstab or an automounter, 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 manually 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 now returns file metadata or the application can open 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 is replacing files behind the export.