Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

NFS "Stale file handle": what changed on the server and how to remount

Technical article
Troubleshooting

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

When a Linux client reports Stale file handle on an NFS mount, the server has told it that the file handle it holds is no longer valid. The reasons the RFCs give are that the file or directory no longer exists or was removed on the server, or that the filesystem holding it is no longer available; a note on a Red Hat solution adds that changing the server's configuration while clients are mounted can leave a share stale. Work out what changed on the server first. Then stop the programs using the mount, unmount it, and mount it again.

What the error means

The errno(3) manual lists ESTALE as "Stale file handle (POSIX.1-2001)" and adds "This error can occur for NFS and for other filesystems."

An NFS file handle is the server's name for an object. RFC 1813 says the handle "contains all the information the server needs to distinguish an individual file", and that "To the client, the file handle is opaque." The RFC adds that "Servers can revoke the access provided by a file handle at any time". If the object no longer exists, or access to it has been revoked, the server returns NFS3ERR_STALE, which the RFC defines as "Invalid file handle. The file handle given in the arguments was invalid." The errno(3) page lists ESTALE and the RFC defines NFS3ERR_STALE; neither page describes how a Linux client maps one to the other.

NFS version 4 behaves the same way. RFC 7530 section 4.2.2 says a persistent filehandle "will become stale or invalid when the file system object is removed", and that "A filehandle may become stale when the file system containing the object is no longer available". It lists the cases: removable media gone, the filesystem destroyed, or the filesystem "removed from the server's namespace".

The exports(5) manual explains what the server uses to identify an exported filesystem. "Normally it will use a UUID for the filesystem (if the filesystem has such a thing) or the device number of the device holding the filesystem", and the fsid= option exists to set the identifier explicitly. A handle can therefore stop matching when the identifier of the filesystem behind an export changes, although exports(5) does not say so in those words.

A stale handle is not a permission fault. See "mount.nfs: access denied by server while mounting: check the export, the client address and the source port" for a refused mount.

Likely causes

Cause What you see How to confirm
A file or directory the client had open was deleted or replaced on the server Stale errors for one path; the rest of the mount works The path is gone or has a new identity on the server
The filesystem under the export was recreated, restored or replaced All paths on the mount are stale Ask what was done to the server's volume; RFC 7530 section 4.2.2 names a destroyed filesystem among the ways a filehandle goes stale
The export was removed or changed on the server while clients were mounted All paths on the mount are stale after an exportfs or exports change exportfs -v on the server no longer lists the path; a note on a Red Hat solution about a different error (access denied while mounting) says changing configuration with clients mounted can leave the share stale
The filesystem identifier changed (no fsid=; device number or UUID differs) Stale after a server reboot or storage change The server's exports line has no fsid=, so (exports(5)) the server uses the filesystem's UUID or device number
subtree_check with renamed files Stale errors for files that were renamed The export line has subtree_check; exports(5) says it "can cause problems with accessing files that are renamed while a client has them open"
A different server answered after a failover Stale on all paths after a failover The clustered or replicated server does not give the same handles; RFC 7530 section 4.2.2 says a filehandle may become stale when its filesystem is no longer available

Prove the cause before changing anything

All of these are read-only.

1. Confirm it is an NFS mount and see its settings. On the client:

findmnt -t nfs,nfs4

The findmnt manual says -t, --types list limits the output to the listed filesystem types, comma-separated. findmnt prints a SOURCE and a TARGET column for each mount, so you can match the failing mount point to its entry.

2. Reproduce with one path. Run ls on the mount point and on a path inside it. If only one path fails, the object may have been deleted or replaced; if the mount point itself fails, the whole export may be stale.

3. Check the server's exports. On the server:

exportfs -v

The exportfs manual says -v also displays the export options when it shows the current list. Look for the exported directory and whether it carries fsid=. Then read /etc/exports and note whether subtree_check is set.

4. Ask what changed. Was the server rebooted, the volume restored or reformatted, an export removed, a failover done, or a directory replaced by a sync job with deletion? The history decides the fix.

5. Look from a second client. If a freshly mounted second client sees the data, only the first client's handles are stale.

Fix

A remount cures the client side only. If the server keeps changing the identifier or removing the object, it will happen again.

Remount on the client

Disruptive step: unmounting stops access to the share for every program using it. Stop or pause the applications that use the mount first (use the service's own stop command), and note which they were. Write down the mount's entry as it is now:

findmnt -t nfs,nfs4 > /root/nfs-mounts-2026-11-20.txt

Then unmount:

umount /mnt/data

If the unmount fails because the server is unreachable, the umount manual describes -f, --force as "Force an unmount (in case of an unreachable NFS system)" and warns that "this option does not guarantee that umount command does not hang". It also describes -l, lazy unmount, which detaches the filesystem now and cleans up later, with a warning that "A system reboot would be expected in near future" when it is used for a network filesystem. Treat -l as a last resort, and plan a reboot.

Then mount again. If the mount is in /etc/fstab, the mount manual says you can give just the mount point:

mount /mnt/data

To back out of the remount, restore the previous state by mounting with the same server, path and options that the saved listing shows. Start the applications again and check them.

Changes on the server

Disruptive step: any change to exports can make mounted clients stale, which matches a note on a Red Hat solution about a different error (access denied while mounting): "Share should be unmounted from all the clients before making any configuration changes on the NFS server, else the share will become stale". Unmount on every client first.

To set an explicit identifier or turn off subtree checking, first print the current export list and save the file:

exportfs -v > /root/exportfs-2026-11-20.txt
cp -a /etc/exports /etc/exports.2026-11-20

Risk: changing the fsid of an export that clients already mounted makes their handles invalid, so every client must remount. To back out, copy /etc/exports.2026-11-20 back over /etc/exports, run exportfs -ra, show the list with exportfs -v, and remount on the clients.

Then edit the export line, for example adding fsid= with a number that no other export on the server uses and that is not 0 (exports(5) says NFS needs to be able to identify each filesystem that it exports, and fsid=0 or root marks the NFSv4 root), or no_subtree_check. exports(5) says changes apply with exportfs -ra or a restart of the NFS server. exports(5) and exportfs(8) document no syntax check for the exports file, so display the result with exportfs -v and test one client before the rest. exports(5) states that the default since nfs-utils 1.1.0 is no_subtree_check, and that a filesystem that sees many renames should be exported with subtree checking disabled.

Example (illustrative): app01 mounts nas01:/export/data at /mnt/data. After the volume behind the export is restored on nas01, ls /mnt/data returns Stale file handle. findmnt -t nfs,nfs4 on app01 confirms the mount. exportfs -v on nas01 shows the export in place without an fsid=. A second client that has never mounted before mounts it and sees the files. The administrator stops the service on app01, runs umount /mnt/data, then mount /mnt/data, and starts the service.

Confirm the fix

  1. ls on the mount point and on paths inside it works without error.
  2. The application's own file operations succeed, including a write if the mount is writable.
  3. After the next server reboot or planned failover, check that the mount stays healthy.
  4. Data you expect is present. A remount does not bring back files that were deleted on the server.

What to watch afterwards

  • Give each export a stable identifier if it lives on storage that can change.
  • Tell NFS users before server changes, and unmount first.
  • Alert on stale errors in application logs.
  • After a restore onto the server, remount every client as part of the runbook.

Risks and limits

  • These commands have not been run or lab-tested.
  • The documented parts are the definition of the error, the file handle behaviour in the RFCs, and the export options in exports(5). The server-side causes in the table follow from the filehandle rules in the RFCs and exports(5); the RFCs and exports(5) do not list each of them.
  • The RFCs and manual pages give no figure for how long a handle stays valid.
  • Hard and soft mount options, caching and failover products are separate topics and are not covered here.
  • A forced or lazy unmount can leave processes hanging, as the umount manual warns.

Sources