FreeBSD 12 – Common Problem 022 – NFS Mounts Timeout or Stall Under Load

📖 ~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

Mounted shares hang, causing application timeouts and blocked IO.

Environment & Reproduction

Client systems using hard mounts against busy or latent NFS servers.

Root Cause Analysis

RPC service instability, packet loss, or unsuitable mount flags for workload profile.

Quick Triage

Inspect NFS services and mounts.

service nfsclient status
mount -t nfs
rpcinfo -p nfs-server

Step-by-Step Diagnosis

Test server export health and network path quality.

showmount -e nfs-server
nfsstat -c
ping -c 20 nfs-server

Solution – Primary Fix

Tune mount options and ensure required daemons are enabled.

sysrc nfs_client_enable='YES'
service nfsclient restart
mount -t nfs -o vers=4,tcp,retrycnt=3 nfs-server:/data /mnt/data

Solution – Alternative Approaches

Use automount and shorter idle timeouts for intermittent access patterns.

Verification & Acceptance Criteria

Sustained read/write tests complete without hangs or RPC timeout errors.

Rollback Plan

Unmount share and restore prior mount options from `/etc/fstab`.

Prevention & Hardening

Monitor RPC error rates and place NFS traffic on low-latency network segments.

Related Errors & Cross-Refs

`nfs server not responding`, stale file handle, blocked D state IO.

Related tutorial: View the step-by-step tutorial for freebsd-12.

View all freebsd-12 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

`mount_nfs(8)`, `nfsstat(1)`, FreeBSD NFS handbook chapters.