🚨 Linux Error: Stale file handle — Cause, Fix, and Troubleshooting Guide

Summary

Stale file handle maps to the errno ESTALE (116). It is almost always an NFS error: the client is holding an NFS file handle that the server no longer recognizes. NFS handles reference a file by its inode/generation number, so if the file was deleted and recreated, the export was recreated, or the server rebooted with a new fsid, the client’s cached handle points at nothing — and every operation on it returns Stale file handle.

Common Symptoms

• ls, cat, or writing to a specific path on an NFS mount returns Stale file handle.
• The error appears after the NFS server was rebooted, re-exported, or failed over.
• A directory a process is sitting in becomes stale while sibling paths still work.
• cd into a previously working NFS directory fails; a fresh cd from the mount root sometimes works.
• Applications that held a file open across a server change get ESTALE on the next read/write.

Most Likely Causes of the ‘Stale file handle’ Error

The Stale file handle error means the NFS file handle no longer resolves on the server. Ranked by production frequency:

1. The file or directory was deleted (and often recreated) on the server or by another client while this client held a handle to it — the inode/generation no longer matches.
2. The NFS server was rebooted or failed over and came back with a different fsid/export identity, invalidating every outstanding handle.
3. The export was changed — re-exported, path moved, or exportfs -r run — so handles issued under the old export are rejected.
4. A process held a long-lived open handle or CWD across any of the above; its cached handle is now stale even though the path exists again.
5. fsid mismatch after storage migration (backing filesystem restored/rsynced to new inodes) so previously valid handles break.

Quick Triage

# Confirm it is an NFS mount and see the server/export
findmnt -t nfs,nfs4
nfsstat -m
# Does the server still export this path?
showmount -e <nfs-server>

If the mount is NFS and the server was recently rebooted or re-exported, a stale handle is the expected result.

Diagnostic Commands

# Which mounts are NFS, and with what options/fsid behavior
findmnt -t nfs,nfs4
nfsstat -m
cat /proc/mounts | grep -E 'nfs '

nfsstat -m shows per-mount options (hard/soft, timeo, vers) that affect how the client reacts to a stale handle.

# Verify the server is up and still exporting the path
showmount -e <nfs-server>
rpcinfo -t <nfs-server> nfs
ping -c2 <nfs-server>

# Find local processes still holding the stale path open
sudo lsof +D /mnt/nfs 2>/dev/null
sudo fuser -vm /mnt/nfs
# Kernel-side NFS messages
dmesg -T | grep -i nfs | tail

If showmount -e succeeds but the specific path is still stale, the file was recreated with a new inode; if the whole export is gone, the server side changed.

Fix / Remediation

1. Retry from the mount root. A stale handle to one path can clear by re-walking from the top — cd / then cd /mnt/nfs and re-open the file. Applications should reopen by path, not reuse the old descriptor.

2. Stop processes holding the stale handle, then remount the export cleanly:

   sudo fuser -vm /mnt/nfs
   sudo systemctl stop <service-using-mount>
   sudo umount /mnt/nfs && sudo mount /mnt/nfs

3. If a normal unmount fails because a process is wedged on the stale mount, lazy-unmount then remount:

   sudo umount -l /mnt/nfs
   sudo mount /mnt/nfs

   Warning: umount -f/umount -l can drop unflushed writes. Stop the writers and let the client flush before forcing; on a genuinely stale export there is nothing left to flush, but on a merely-slow server there may be.

4. Fix the server-side identity. If the stale handle followed a reboot/migration, pin a stable fsid= in /etc/exports so handles survive re-exports and failover, then exportfs -ra on the server.

Validation

# The path resolves and reads cleanly after remount
ls -la /mnt/nfs && cat /mnt/nfs/<file> >/dev/null && echo "handle valid"
nfsstat -m

A successful ls/cat with no ESTALE confirms the client picked up fresh handles.

Prevention

• Pin fsid=<n> for every NFS export in /etc/exports so the export identity is stable across server reboots and failover — the single biggest cause of avoidable ESTALE.
• Mount NFS hard with a bounded timeo/retrans so transient server changes retry instead of returning stale immediately.
• Coordinate deletes/recreates: avoid delete-then-recreate churn on shared paths that many clients hold open.
• Have applications reopen files by path (and handle ESTALE by retrying) rather than caching descriptors across long idle periods.
• Monitor NFS server reboots/failovers and remount clients as part of the failover runbook.

Related Errors

• Transport endpoint is not connected
• Input/output error
• Device or resource busy
• Read-only file system

Final Notes

Stale file handle is an NFS identity problem: the client’s cached handle references a file/inode the server no longer recognizes after a delete-recreate, reboot, or re-export. Reopen by path, remount the export, and — most importantly — pin a stable fsid= on the server so handles survive the next restart. It is not disk corruption, so no fsck is needed; the fix lives in the NFS export config and the client’s remount.

Want faster Linux incident response? Use DevOps AI Toolkit to turn production errors into clear diagnostics, remediation steps, and reusable runbooks.