The first time I set up an NFS share on TrueNAS, I spent forty minutes convinced my network was broken. The share existed, the pool was healthy, and the mount command just kept spitting back access denied by server. Nothing was wrong with the network at all.
The real problem was three settings hiding in the share config that TrueNAS does not warn you about. Once you know where they live, this whole class of error takes about five minutes to clear.
This walkthrough covers the two failures I see most from home users mounting a TrueNAS SCALE or CORE export on a Linux box: the access or permission denied wall, and the dreaded stale file handle. We will go in the order that actually resolves them, starting with the checks that catch ninety percent of cases.
Confirm the export is actually being served
Before touching any config, prove the server is offering the share to your client. From the Linux machine, run a quick query against the TrueNAS IP.
Use showmount -e 192.168.1.50 (swap in your NAS address). You should see the export path and the hosts allowed to reach it.
If showmount returns nothing or times out, the NFS service is either off or firewalled. On TrueNAS SCALE, check System Settings, then Services, and confirm NFS is running and set to start automatically.
If showmount lists your path but with a host restriction you did not expect, that is your next lead. Note exactly what it prints, because that string is what we compare against in the next step.
Fix access denied: the allowed hosts trap
This is the single most common cause. In the TrueNAS share settings under Shares, then Unix Shares (NFS), open your export and look at the Networks and Hosts fields.
Here is the part that trips everyone. If you type a single IP into Hosts, only that exact address may mount. Your laptop on 192.168.1.31 will be refused if you allowed 192.168.1.30.
A mistake I see constantly: people put the network in the wrong notation. The Networks field wants CIDR like 192.168.1.0/24, not a plain 192.168.1.0 or a subnet mask.
My advice for a home LAN is to leave both fields empty first, save, and test the mount. An empty allowed-hosts list means any client can reach it, which is fine while you debug on a trusted home network. Once the mount works, come back and lock it to your subnet.
Fix permission denied after a successful mount
Sometimes the mount succeeds but you cannot write, or even list, the folder. The share attached fine, so this is a user-mapping problem, not a host problem.
TrueNAS datasets are owned by a specific user and group. If your Linux user has UID 1000 and the dataset is owned by UID 950, the server sees a stranger and blocks writes.
The clean fix lives in the share's advanced options. Set Mapall User and Mapall Group so every incoming request is treated as an owner the dataset trusts.
Which mapall values to pick
For a simple home setup where you just want it to work, mapping to the dataset owner is the pragmatic choice. Here is how the common options behave.
| Setting | Effect | Good for |
|---|---|---|
| Mapall User = owner of dataset | All clients act as that user, full read/write | Single-user home shares |
| Mapall User = root | Everyone gets root-level access to the share | Trusted admin box only |
| Maproot User = root | Only client root is remapped, other users keep their UID | Mixed setups with matching UIDs |
| Nothing set | Server enforces raw UID match | Networks where UIDs are synced |
After changing mapall, you must restart the NFS service or at least remount from the client. TrueNAS does not always apply the new mapping to an already-connected session, which is why people swear it did nothing.
Unmount with sudo umount /mnt/nas, then mount again. If it was a mapping issue, your permission error is gone.
Fix stale file handle errors
A stale NFS file handle means the client is holding a reference to something the server no longer recognizes. The handle pointed at an inode, and that inode moved or vanished.
The usual culprits at home are a NAS reboot, a dataset that got recreated, or an export path that changed. The client keeps clutching the old handle and the server rightly says no.
The fix is almost always a forced unmount and clean remount. Try sudo umount -f /mnt/nas first.
If that refuses because the mount is busy, use a lazy unmount: sudo umount -l /mnt/nas. This detaches it once nothing is using it, then you can mount fresh.
If stale errors keep coming back on their own, check whether autofs or systemd is remounting an export that no longer exists. A leftover entry in /etc/fstab pointing at an old path will fight you forever.
A mount command that behaves
Half the flaky mounts I get asked about use a bare command with no options. Adding a couple of sensible flags removes most of the pain.
- Specify the version so client and server agree: add -o vers=4 (TrueNAS SCALE defaults to NFSv4).
- Use -o soft,timeo=30 during testing so a bad mount fails fast instead of hanging your terminal.
- Point at the full dataset path shown by showmount, for example /mnt/tank/media, not a guessed path.
A full command looks like sudo mount -t nfs -o vers=4 192.168.1.50:/mnt/tank/media /mnt/nas. If that works by hand, only then move it into fstab.
For the version details, the official TrueNAS documentation is worth a bookmark, and the general concept is well summarised on the Network File System overview if you want the background.
Put it in fstab without breaking boot
Once a manual mount works, you probably want it automatic. But a stubborn NFS line in fstab can hang a Linux boot for minutes if the NAS is off.
Add _netdev,nofail,x-systemd.automount to the options. That tells systemd to wait for the network, not to panic if the NAS is missing, and to mount on first access rather than at boot.
A sane fstab line reads: 192.168.1.50:/mnt/tank/media /mnt/nas nfs vers=4,_netdev,nofail,x-systemd.automount 0 0. Test it with sudo mount -a before you reboot, so you catch typos while you still have a shell.
When it still refuses
If you have cleared allowed hosts, set mapall, and remounted clean but still get denied, check two last things. Confirm the dataset actually exists at the path you are mounting, and confirm the NFS service restarted after your last change.
Nine times out of ten the culprit was the allowed-hosts field or a mapall mismatch, and both are two-minute fixes once you know the pattern. Get one clean manual mount working before you automate anything, and future you will thank you.
Frequently asked questions
Why does my TrueNAS NFS mount say access denied by server while exporting?
The client IP is not in the share's allowed list. Open the NFS share in TrueNAS and check the Hosts and Networks fields. Either add your client's subnet in CIDR form such as 192.168.1.0/24, or empty both fields to test, then restart the NFS service.
I can mount the TrueNAS share but cannot write to it. Why?
That is a UID mismatch, not a mount problem. Your Linux user's UID does not match the dataset owner, so the server blocks writes. Set Mapall User and Mapall Group in the share's advanced options to the dataset owner, then remount.
How do I clear a stale NFS file handle on Linux?
Force unmount with sudo umount -f /mnt/nas, or use a lazy unmount sudo umount -l /mnt/nas if it reports the mount is busy. Then mount again. Stale handles usually appear after a NAS reboot or a recreated dataset.
Should I use NFSv3 or NFSv4 with TrueNAS SCALE?
TrueNAS SCALE defaults to NFSv4, so pass vers=4 in your mount command to avoid a version mismatch. NFSv3 still works if you enable it, but matching the server default prevents a whole class of silent failures.
How do I stop an NFS mount from hanging my Linux boot?
Add _netdev, nofail, and x-systemd.automount to the fstab options. These wait for the network, skip the mount silently if the NAS is off, and only mount on first access, so a powered-down NAS never blocks startup.
