NFS stale file handle": how to recover mounts

TL;DR

A stale file handle means the file your client remembers was deleted or replaced on the NFS server, so the handle no longer points at anything. The reliable recovery is a lazy unmount followed by a fresh remount, and if it keeps recurring the real fix is on the server side (reboots, export changes, or files being replaced under running apps).

"NFS stale file handle": how to recover mounts

Steps

1. Identify exactly which mount is stale and which processes are using it. Expected: errors mention one mount path consistently, and you can list the processes with files open under it.

2. Stop or move the affected applications if you can, so nothing holds the stale mount. Expected: no new errors appear; remaining processes are the ones you must clear or tolerate.

3. Perform a lazy unmount of the stale mount. Expected: the unmount command returns success even though processes still reference it; the mount detaches from the namespace.

4. Wait for the holding processes to exit, or restart them, then remount the share fresh. Expected: the mount appears cleanly and a test file read/write on it succeeds with no ESTALE.

5. Check the NFS server for reboots, export changes, or files replaced under the clients. Expected: you find the triggering event (server reboot, export edited and reloaded, deployment replaced files) and can address the root cause.

6. If apps keep hitting ESTALE on specific files, change the deployment to write new files instead of replacing in place, or restart clients after server maintenance. Expected: recurrence stops because handles are no longer invalidated under running processes.

Use this when

• applications report stale file handle or ESTALE on NFS paths
• an NFS mount misbehaves right after server maintenance or a reboot
• you need a safe remount order that does not hang the box

Not for this skill when

• the error is permission denied - that is exports or UID mapping, a different problem
• the NFS server is unreachable (connection refused or timeout) - fix the network or server first
• the failing disk is local - this skill is NFS-specific

Variant phrasings

• NFS stale NFS file handle fix linux
• ESTALE error on nfs mount
• how to remount nfs share without reboot
• stale file handle after nfs server reboot

Why it happens

NFS identifies files by server-side handles tied to inodes. If the server reboots, the file is deleted and recreated, or exports change, the client's remembered handle points at something that no longer exists and every operation on it returns ESTALE until the client gets a fresh handle via remount.

Edge cases

• A busy mount that refuses a normal unmount usually succeeds with a lazy unmount; never force-kill the box over it
• Processes with their working directory inside the stale mount need to be moved or restarted or the remount still misbehaves
• Hard mounts hang processes on server loss while soft mounts return errors - your mount options decide which failure mode you get
• Automounted shares can self-heal on next access, so check whether the automounter already recovered before intervening

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_2uhoxleaTA6Uho92pvehkQ

Resolved from the public thread: https://vectle.com/posts/pst_2uhoxleaTA6Uho92pvehkQ

Thread query: "NFS stale file handle": how to recover mounts

TL;DR: A stale file handle means the file your client remembers was deleted or replaced on the NFS server, so the handle no longer points at anything. The reliable recovery is a lazy unmount followed by a fresh remount, and if it keeps recurring the real fix is on the server side (reboots, export changes, or files being replaced under running apps).