FreeBSD 14 – NFS mounts return stale file handle after server updates – Fix & Prevention

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

Applications fail I/O on mounted shares with stale file handle errors.

Environment & Reproduction

Often after export path changes, dataset recreation, or server reboot events.

mount -t nfs
ls -la /mnt/share
dmesg | grep -i nfs

Root Cause Analysis

Server-side inode/filehandle mapping changed while client retained old mount context.

Quick Triage

Check server export list and client mount options.

showmount -e nfs-server
nfsstat -m
cat /etc/fstab | grep nfs

Step-by-Step Diagnosis

Trace client retries and verify server exports are unchanged and reachable.

tcpdump -ni any host nfs-server and port 2049 -c 40
rpcinfo -p nfs-server
service nfsclient status

Solution – Primary Fix

Unmount stale share, clear state, and remount with validated export path.

umount -f /mnt/share
service nfsclient restart
mount /mnt/share

Solution – Alternative Approaches

Use automount maps with shorter timeout and soft failover policies.

sysrc autofs_enable="YES"
service automount start

Verification & Acceptance Criteria

Read/write tests succeed and stale handle messages stop in logs.

touch /mnt/share/.rw-test
rm -f /mnt/share/.rw-test
dmesg | grep -i 'stale file handle'

Rollback Plan

Revert to prior export path mapping if remount strategy impacts application paths.

mount -o vers=3 nfs-server:/old/export /mnt/share

Prevention & Hardening

Coordinate export changes with client remount windows and change notifications.

nfsstat -c
nfsstat -s

Related Errors & Cross-Refs

Associated with DNS drift, lockd issues, and stale automount caches.

Related tutorial: View the step-by-step tutorial for FreeBSD 14.

View all FreeBSD 14 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

FreeBSD NFS server/client administration and troubleshooting docs.