Linux users often run into confusing error messages. The Stale File Handle warning is one of them. It appears when a folder gets removed and rebuilt while a program still references the old location.
This guide covers the cause and how to deal with it on local and NFS-mounted filesystems.
Inodes and File Descriptors: A Quick Primer on the Stale File Handle Error
Each file or folder on a Linux system gets an inode, a metadata container that stores size, permissions, and data block locations. Every inode carries a unique number on its partition.
A file descriptor is a reference a running program keeps after opening a file. When the inode behind that reference disappears, the descriptor goes invalid and the Stale File Handle message shows up. To find which programs hold open references, you can list active processes on your system.
Why Removing and Rebuilding a Folder Triggers the Stale File Handle Problem
The delete-and-recreate cycle breaks down like this:
| Stage | Action | Result |
|---|---|---|
| 1 | Folder /data/docs exists with inode 12345 | A program opens it, holding a reference to inode 12345 |
| 2 | You run rm -rf /data/docs |
The name entry is erased; inode 12345 may not be freed yet |
| 3 | You run mkdir /data/docs |
A fresh folder appears with a new inode (e.g., 67890) |
| 4 | The program tries to read using its old reference | Inode 12345 no longer matches anything — Stale File Handle appears |
The folder name looks identical, but the inode behind it changed. Any program pointing at the old inode fails.
Common Situations That Produce the Stale File Handle Error
| Situation | Explanation |
|---|---|
| NFS mounted shares | Clients cache inode references from remote servers. If the server rebuilds a folder, cached references go bad. |
| Shell sessions inside a removed folder | Your terminal still points at the old inode after recreation. |
| Containers with host mounts | Docker or Kubernetes pods lose access if mounted host folders get replaced. |
NFS setups are the most frequent source. If you manage remote file transfers, see how SCP works between Linux and Windows.
Diagnosing the Stale File Handle Error
Run ls -ld /path/to/folder first. If the output says “Stale file handle,” the issue is confirmed. Use ls -i to compare inode numbers before and after recreation.
Run lsof +D /path/to/folder to spot programs holding the old reference. This lists every open file descriptor under the given path.
Resolving the Stale File Handle Issue
You can fix this a few ways. Terminate or restart the offending program. For shell sessions, type cd /tmp then cd back to the recreated path.
On NFS clients, unmount and remount the share with umount -l /mnt/share then mount -a. You can also restart services like NGINX if a daemon holds the dead reference. A full reboot works as a last option.
Avoiding the Stale File Handle Error Going Forward
Check for open references with lsof or fuser before removing any folder. Swap folders with symbolic links instead of deleting and recreating.
On NFS servers, rename old folders rather than removing them. This gives clients time to release cached handles. For related troubleshooting, see how to fix shared library loading errors.
FAQs
What does “Stale File Handle” mean in Linux?
It means a program holds a reference to an inode that no longer exists. The filesystem replaced the original inode, so the reference is outdated.
Does the Stale File Handle error only happen with NFS?
No. It also affects local shell sessions, Docker containers with host mounts, and any process that keeps a directory reference when that directory gets removed and recreated.
How do I fix a Stale File Handle error on an NFS mount?
Unmount the share with umount -l /mnt/share, then remount with mount -a. The lazy flag avoids “device is busy” blocks.
Can I prevent the Stale File Handle error entirely?
You can reduce it by checking open references with lsof before removing folders, using symlinks for swaps, and renaming folders on NFS servers instead of deleting them.
Will rebooting the system clear a Stale File Handle error?
Yes. A reboot releases all file descriptors and remounts filesystems. Use it as a last resort when unmounting and restarting services fail.
