How to troubleshoot NFS file locking

NFS file locking problems usually appear when an application cannot create a lock file, waits on a shared file indefinitely, or reports that no locks are available while ordinary reads still work. Lock failures need their own checks because they depend on protocol state and mount options, not only on directory permissions.

On current Linux clients, NFSv4 carries file open and lock state in the main NFS protocol. NFSv3 uses separate Network Lock Manager and Network Status Monitor traffic, so rpc.statd, rpcbind, firewall rules, and server RPC registration matter when an older mount is involved.

Use the exact NFS path, client, and application user that saw the failure. A same-client test can show that the local process can take a lock, but a two-client test is the proof that the server is enforcing remote exclusion instead of only local locking.

Steps to troubleshoot NFS file locking:

Reproduce the lock failure as the affected user on the affected client.
```
$ flock --nonblock --verbose /mnt/projects/build.lock --command 'true'
flock: failed to get lock
```
Replace /mnt/projects/build.lock with the lock file or application path that failed. A lock that is already held should fail this way with --nonblock; No locks available or repeated hangs point toward lock service, mount option, or server state trouble.

Identify the live NFS mount behind the failing path.

$ findmnt --target /mnt/projects --types nfs,nfs4 --output TARGET,SOURCE,FSTYPE,OPTIONS
TARGET        SOURCE                                FSTYPE OPTIONS
/mnt/projects files.example.net:/srv/nfs/projects nfs4   rw,relatime,vers=4.2,rsize=1048576,wsize=1048576,hard,proto=tcp,sec=sys

If no row appears, troubleshoot the mount path before changing lock settings. Use the FSTYPE and vers= option to decide whether the lock path is NFSv4 or NFSv3.
Related: How to check the NFS version for a mounted export

Check whether the mount is using client-local locks.
```
$ nfsstat --mounts
/mnt/projects from files.example.net:/srv/nfs/projects
 Flags: rw,vers=4.2,rsize=1048576,wsize=1048576,hard,proto=tcp,sec=sys
```
If the flags include nolock, local_lock=all, local_lock=flock, or local_lock=posix, locks may protect only processes on the same client. Remove those options unless the application specifically requires local-only locking.
Edit the saved mount entry when an accidental local-lock option is present.
```
$ sudoedit /etc/fstab
```
```
files.example.net:/srv/nfs/projects /mnt/projects nfs4 rw,_netdev,x-systemd.automount 0 0
```
Keep site-required options such as sec=krb5 or vers=3. Remove only lock options that made remote locking local or disabled NLM locking unexpectedly.

Related: How to mount an NFS export on Linux
Unmount the affected client mount after stopping applications that keep files open.
```
$ sudo umount /mnt/projects
```
Do not force the unmount while the application is still writing through the share. Stop the service or process that owns the lock file first.
Mount the export again from the saved entry.
```
$ sudo mount /mnt/projects
```
Check NFSv3 lock services only when the live mount uses vers=3.
```
$ systemctl is-active rpc-statd rpcbind
active
active
```
NFSv4 does not use the separate NLM and NSM sideband protocols. For NFSv3, an inactive rpc-statd or rpcbind service can break lock recovery or prevent remote locking from working.
Start missing NFSv3 client lock services.
```
$ sudo systemctl start rpc-statd rpcbind
```
Use this only for an NFSv3 mount. If either unit is missing, install the distribution NFS client utility package and recheck the mount.

Related: How to install an NFS client on Ubuntu
Related: How to install an NFS client on CentOS Stream, RHEL, and Fedora
Verify that the server advertises NFSv3 lock services when the mount uses vers=3.
```
$ rpcinfo -p files.example.net
   program vers proto   port  service
    100000    4   tcp    111  portmapper
    100003    3   tcp   2049  nfs
    100021    4   tcp  32803  nlockmgr
    100024    1   tcp    662  status
```
If nlockmgr or status is missing or unreachable for an NFSv3 mount, fix the NFS server services or firewall before retesting the application. NFSv4 clients normally do not need these separate RPC programs.

Related: How to check NFS server status in Linux
Related: How to allow NFS server traffic through firewalld
Related: How to configure fixed NFSv3 ports for firewall rules
Hold a test lock from another NFS client or another shell that represents the first application instance.
```
$ flock /mnt/projects/build.lock --command 'sleep 300'
```
Use a second client when the incident involves multiple clients. A same-client test proves only local process contention and cannot detect accidental client-local locking.
Test the same lock from the affected client while the first lock is still held.
```
$ flock --nonblock --verbose /mnt/projects/build.lock --command 'true'
flock: failed to get lock
```
This is the expected result while the other client holds the lock. If the second client acquires the lock at the same time, recheck nolock, local_lock=, the protocol version, and the server lock service path.
Press Ctrl-C in the shell that is running sleep 300.
Retest the lock after the holder exits.
```
$ flock --nonblock /mnt/projects/build.lock --command 'echo lock acquired'
lock acquired
```
The lock path is usable again when the same file blocks a second holder during contention and allows a new holder after release.
Remove the temporary lock file if it was created only for troubleshooting.
```
$ rm /mnt/projects/build.lock
```
Do not remove an application-owned lock file unless the application vendor or runbook says it is safe. For real application locks, restart or retry the application after the lock test proves the NFS path behaves correctly.